I have two weeks left to get all my testing documentation together for a single project (including writing new material, inevitably) before I leave my current job. Fortunately this is the only task I have left to do, there are no other demands on my time, and I’ve time enough to do it. This has given me pause to consider why “documentation” is a dirty word and what approaches might help remedy the negative perception and, more importantly, allow space and time for it actually to be completed.

Some thoughts, then…

• If the documentation is not defined as a project deliverable then–guess what–it will not be delivered.
• As such, you’re relying on sheer good will for it to appear at all which is plainly not realistic. It’s enough just to get the software out in the time available. Anything else will go to the wall.
• Every user claims to want documentation but with no clear indication of the general literacy of the user base. This requires effort to establish before documentation should even be started.
• If resources are taken away to write documentation or the release date is pushed back to accommodate the same, users will clamour for the software instead.
• I can’t stress this one enough: useful documentation seems to take about as much time to produce and get right as the software it describes.
  
• Any documentation that is produced tends to be either rather sparse or, conversely, detailed to the point of near-uselessness (eg “this is how you use the mouse”). Often an author without clear direction will lurch somewhere between the two extremes, redrafting furiously in an attempt to strike a balance.
• Developers/designers/architects suffer from the illusion that “making the UI intuitive” will preclude the need for documentation. Brave attempts are made towards this but intuition is like common sense: everyone thinks they know what it is, but it’s different for every person.
• The documentation needs testing as well (proofreading, walkthroughs, etc).
• It should be sent for review to the user base, as well as within the project team.
• The very act of writing the documentation means you look at the software from a inherently different angle (often the reverse angle).
• As such, you’ll probably spot things about the software that have never been considered (it’s a rather baroque form of testing). This might necessitate a change to the system, which will in turn need to be reflected in the documentation. This tightly-closed feedback loop really ought to be followed to exhaustion.