Types of Software Documentation


If your software's documentation consisted of nothing but a simple readme file, testing it wouldn't be a big deal. You'd make sure that it included all the material that it was supposed to, that everything was technically accurate, and (for good measure) you might run a spell check and a virus scan on the disk. That would be it. But, the days of documentation consisting of just a readme file are gone.

Today, software documentation can make up a huge portion of the overall product. Sometimes, it can seem as if the product is nothing but documentation with a little bit of software thrown in.

Here's a list of software components that can be classified as documentation. Obviously, not all software will have all the components, but it's possible:

  • Packaging text and graphics. This includes the box, carton, wrapping, and so on. The documentation might contain screen shots from the software, lists of features, system requirements, and copyright information.

  • Marketing material, ads, and other inserts. These are all the pieces of paper you usually throw away, but they are important tools used to promote the sale of related software, add-on content, service contracts, and so on. The information for them must be correct for a customer to take them seriously.

  • Warranty/registration. This is the card that the customer fills out and sends in to register the software. It can also be part of the software, being displayed onscreen for the user to read, acknowledge, and complete online.

  • EULA. Pronounced "you-la," it stands for End User License Agreement. This is the legal document that the customer agrees to that says, among other things, that he won't copy the software nor sue the manufacturer if he's harmed by a bug. The EULA is sometimes printed on the envelope containing the mediathe floppy or CD. It also may pop up onscreen during the software's installation. An example is shown in Figure 12.1.

    Figure 12.1. The EULA is part of the software's documentation and explains the legal terms of use for the software.


  • Labels and stickers. These may appear on the media, on the box, or on the printed material. There may also be serial number stickers and labels that seal the EULA envelope. Figure 12.2 shows an example of a disk label and all the information that needs to be checked.

    Figure 12.2. There's lots of documentation on this disk label for the software tester to check.


  • Installation and setup instructions. Sometimes this information is printed directly on the discs, but it also can be included on the CD sleeve or as a CD jewel box insert. If it's complex software, there could be an entire installation manual.

  • User's manual. The usefulness and flexibility of online manuals has made printed manuals much less common than they once were. Most software now comes with a small, concise "getting started"type manual with the detailed information moved to online format. The online manuals can be distributed on the software's media, on a website, or a combination of both.

  • Online help. Online help often gets intertwined with the user's manual, sometimes even replacing it. Online help is indexed and searchable, making it much easier for users to find the information they're looking for. Many online help systems allow natural language queries so users can type Tell me how to copy text from one program to another and receive an appropriate response.

  • Tutorials, wizards, and CBT (Computer Based Training). These tools blend programming code and written documentation. They're often a mixture of both content and high-level, macro-like programming and are often tied in with the online help system. A user can ask a question and the software then guides him through the steps to complete the task. Microsoft's Office Assistant, sometimes referred to as the "paper clip guy" (see Figure 12.3), is an example of such a system.

    Figure 12.3. The Microsoft Office Assistant is an example of a very elaborate help and tutorial system.


  • Samples, examples, and templates. An example of these would be a word processor with forms or samples that a user can simply fill in to quickly create professional-looking results. A compiler could have snippets of code that demonstrate how to use certain aspects of the language.

  • Error messages. These have already been discussed a couple times in this book as an often neglected area, but they ultimately fall under the category of documentation.



    Software Testing
    Lessons Learned in Software Testing
    ISBN: 0471081124
    EAN: 2147483647
    Year: 2005
    Pages: 233

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net