I am currently of writing a fairly large software requirements specification for a client. I am acutely aware that in general people don’t like to read documents, and that large terse documents like software development specifications can be especially challenging. To help reduce the amount of effort that readers will have to put into reading and reviewing the document while attempting to increase its usefulness I am doing my best to follow some simple self enforced rules:
1. Avoid using abbreviations (TLAs)
2. Avoid mentioning technologies – this is a requirements spec. after all!
3. Avoid unnecessary Capitals As Much As Possible!
4. Avoid repeating words in a sentence for no good reason
5. Run the spell checker
6. Add a revision number
7. Print out and properly review on paper before releasing to to the client.
Hopefully if I stick to these rules, then the specification will end up as a slightly ‘better’ read.