Testing the documentation

Testing the documentation

• 1.
  Types of SoftwareDocumentation   Today, software documentation can make up a huge portion of the overall product. List of software components that can be classified as documentation: – – – Packaging text and graphics. This includes the box, carton, wrapping, and so on. Marketing material, ads, and other inserts. they are important tools used to promote the sale of related software, add-on content, service contracts Warranty/registration. This is the card that the customer fills out and sends in to register the software. 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.
• 2.
  Types of SoftwareDocumentation    Labels and stickers. These may appear on the media, on the box, or on the printed material. 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.
• 3.
  Types of SoftwareDocumentation     Online help. 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. 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. Error messages.
• 4.
  The Importance ofDocumentation Testing     Software users consider all these individual nonsoftware components parts of the overall software product. They don't care whether the pieces were created by a programmer, a writer, or a graphic artist. What they care about is the quality of the entire package. If the installation instructions are wrong or if an incorrect error message leads them astray, users will view those as bugs with the software ones that should have been found by a software tester.
• 5.
  The Importance ofDocumentation Testing  Good software documentation contributes to the product's overall quality in three ways: 1. 2. 3. It improves usability. All the issues related to a product's usability? Much of that usability is related to the software documentation. It improves reliability. Reliability is how stable and consistent the software is. Does it do what the user expects and when he expects it? If the user reads the documentation, uses the software, and gets unexpected results, that's poor reliability. It lowers support costs. problems found by a customer can cost 10 to 100 times as much as if they were found and fixed early in the product's development. The reason is that users who are confused or run into unexpected problems will call the company for help, which is expensive. Good documentation can prevent these calls by adequately explaining and leading users through difficult areas.
• 6.
  The Importance ofDocumentation Testing  As a software tester, you should treat the software's documentation with the same level of attention and give it the same level of effort that you do the code.  They are one in the same to the user. If you're not asked to test the documentation, be sure to raise this as an issue and work to have it included in your overall testing plan.
• 7.
  What to Lookfor When Reviewing Documentation  Whether or not the documentation is code, a very effective approach to testing it is to: – – – – Treat it just like a user would. Read it carefully, follow every step, examine every figure, and try every example. If there is sample code, type it in and make sure it works as described. With this simple real-world approach, you'll find bugs both in the software and the documentation.
• 8.
  A Documentation TestingChecklist  Audience: –  Does the documentation speak to the correct level of audience, not too novice, not too advanced? Terminology: – – – – – Is the terminology proper for the audience? Are the terms used consistently? If acronyms or abbreviations are used, are they standard ones or do they need to be defined? Make sure that your company's acronyms don't accidentally make it through. Are all the terms indexed and cross-referenced correctly?
• 9.
  A Documentation TestingChecklist  Content – – – – and subject matter: Are the appropriate topics covered? Are any topics missing? How about topics that shouldn't be included, such as a feature that was cut from the product and no one told the manual writer. Is the material covered in the proper depth?
• 10.
  A Documentation TestingChecklist  Just the facts: – – – – – Is all the information factually and technically correct? Look for mistakes caused by the writers working from outdated specs or sales people inflating the truth. Check the table of contents, the index, and chapter references. Try the website URLs. Is the product support phone number correct? Try it.
• 11.
  A Documentation TestingChecklist  Step – – – – – by step: Read all the text carefully and slowly. Follow the instructions exactly. Assume nothing! Resist the temptation to fill in missing steps; your customers won't know what's missing. Compare your results to the ones shown in the documentation.
• 12.
  A Documentation TestingChecklist  Figures – – – – and screen captures: Check figures for accuracy and precision. Do they represent the correct image and is the image correct? Make sure that any screen captures aren't from prerelease software that has since changed. Are the figure captions correct?
• 13.
  A Documentation TestingChecklist  Samples – – – and examples: Load and use every sample just as a customer would. If it's code, type or copy it in and run it. There's nothing more embarrassing than samples that don't work and it happens all the time!
• 14.
  A Documentation TestingChecklist  Spelling and grammar: – – – – Spelling and grammar checkers are too common place not to be used. It's possible, though, that someone forgot to perform the check or that a specialized or technical term slipped through. It's also possible that the checking had to be done manually, such as in a screen capture or a drawn figure. Don't take it for granted.
• 15.
  A Documentation TestingChecklist     Finally, if the documentation is software driven, test it as you would the rest of the software. Check that the index list is complete, that searching finds the correct results, and That the hyperlinks and hotspots jump to the correct pages. Use equivalence partition techniques to decide what test cases to try.
• 16.
  The Realities ofDocumentation Testing      Documentation often gets the least attention, budget, and resources. In reality, it's a software product that people are buying and all that other stuff is at least as important as the bits and bytes. If you're responsible for testing an area of the software, make sure that you budget time to test the documentation that goes along with that code. Give it the same attention that you do the software and if it has bugs, report them. It's possible that the people writing the documentation aren't experts in what the software does.
• 17.
  The Realities ofDocumentation Testing       Most importantly, tell them about difficult-to-use or difficult-tounderstand areas of the code that you discover so they can better explain those areas in the documentation. Printed documentation takes time to produce, sometimes weeks or even months. If the software functionality changes or bugs are discovered during this critical period, the documentation can't be changed to reflect them. That's why the readme file was invented. It's how those last-minute changes are often communicated to users. The solution to this problem is to have a good development model, follow it, hold your documentation release to the last possible minute, and release as much documentation as possible, in electronic format, with the software.