December 18, 2006

...Learn TDD with Codemanship

Documentation Tips

A few tips on documentation, while I have a spare moment:

1. Documentation costs time and money to create and maintain. Plan it like any other kind of requirement, and make the customer choose where it goes in the schedule.

2. Documentation must have a clear audience and purpose. Anyone familar with JavaDoc will know how badly this can go wrong. Consider use cases (usage scenarios) for your documentation; who will be using it and what will they be using it to do? For example, what would someone taking support calls from end users need to be able to do using your documentation? Don't guess. Go and ask them! Have clear user specs for documentation, and also seriously consider agreeing acceptance criteria for documentation, too. For example, if your API documentation is supposed to explain how to send an email, ask one of the intended audience to read it and then send an email. Have clear success criteria. If they take too long, or fail to complete the task, find out why and go back and improve your documentation.

3. Documentation gets out of date every time you change the code. If your documentation doesn't need to be kept up-to-date with the code, then why did you create it in the first place? Maintain high-level traceability between documentation and code, so you have a rough idea of what might need updating with each release of the software. This will cost more time and money, so every new document represents an added burden on the project.

You're much more likely to end up with relavant and useful documentation, and you'll soon find that, with costs measured explicitly and with the extra burden of properly specifying, acceptance testing and maintaining documentation, that customers and managers ask for only the documentation they really, actually need.

One final thought - are requirements specifications "documentation"? My opinion is that they're not. Requirements specs describe the difference between the system now and what the customer wants it to be. Once a feature has been delivered and accepted by the customer, I recommend throwing the spec away. Documentation describes what the system is.
Posted 14 years, 7 months ago on December 18, 2006