Documentation and Test

Ramblings on documentation and test... and test of documentation.


Part 1. Technical Writers vs Testers


I recently had an exchange with Rosie Sherry, the founder of the Software Testing Club, on the relationship between testers and other roles in the software microcosm. This was in response to a piece she wrote in the online version of their magazine, The Testing Planet, regarding the relationship between testers and marketeers. I had some thoughts on the synergies between testers and technical writers, so Rosie invited me to share my thoughts in a followup piece. Here is the link:


Documentation and the Tester


Part 2. Testing Documentation


Well, while I was on the subject ... I offered to share my thoughts on testing documentation. This was posted as a follow-up on the The Testing Planet online.


How to Test Documentation


... but thanks to some responses to the piece I would like to offer an amended list right here:

How To Test Documentation

(updated)

• Proof Read for Spelling and Grammar - Some may sneer at the notion of a technical writer making simple errors. That’s silly. The hard part is organizing information and presenting it cogently. Give me that, and I am more than happy to look for typos.
• Spelling & Grammar Trick –  If you are reviewing documentation in a tool or viewer or format which does not offer native spell and grammar checking, considering importing the text into a tool which does. MS Word, Open Office Writer, Google Docs, a browser add-on – even cat the text file into “spell” on Unix. Take advantage of the tools at hand. But you still have to manually check the content.
• Check the String Tables - Many application use string tables to enable localization. This is where any text that appears in the application interface is separated out from the source code, so that the application can be "localized" for a different international audience by swapping a string table translated to the appropriate audience. Check the string table for spelling and grammar. (See the previous point about using tools to help.)
• Check for Accuracy – errors of commission. Keep the Development Spec and your test notes handy.
• Check for Completeness – errors of omission. Again, use the Dev Spec and test notes for references.
• Consider Organization and Approach – compare with the Marketing Req. Spec.
• Test all Examples! – Do you (or your company) want to look dumb? Include an example in the doc that doesn’t work. I speak from experience here. So don’t just read the examples. Perform the exact steps documented.
• Look for changes in one area that might affect another - And make sure that screenshots are up-to-date.
• Make at least two passes, first for spelling and grammar, then for content - Your brain uses different areas for these activities; you will be much more effective if you do them separately. I have difficulty focusing on content if I am tripping over typos, so I check for those first. In the second pass gives you a better perspective on context, flow, and organization.

Special thanks to Kobi Halperin for the reminder on string tables. And to Jeff Lucas for the pointer to the book Tacit and Explicit Knowledge by Harry Collins, which explains the roles of the "inscripted" vs "translational" areas of the brain in reviewing grammar vs meaning. I thought it was just my own hangup that I needed two passes. :) 

Any more suggestions or comments? I would be happy to update the list.