I hate reading and writing documentation. In fact, I think many people in IT hate reading and writing documentation. It is a necessary evil if you want your projects to be of good quality, consistent and maintainable. My pet peeves in a document are the following:
- Long narratives that babble on.
- No way to understand the big picture
- Documents that are not considerate of the reader’s time
- Reading a document that you know the writer is simply trying to complete
To keep my attention and focus on the documents, I have come up with some rules for my staff that are working pretty well. They are as follows:
Split your document into smaller documents
An easy way to do this is to create a document that is focused on a particular objective and audience. For example, instead of having one large document that contains, the business process flow, business requirements and system requirements. Break them up into three documents.
Don’t repeat information from one document to the other
I see it all the time. The Policy regurgitated in the Business Requirements document. Don’t give in to that temptation even if you think it will help make the document more complete. It will only add more pages for the reader to skim and ignore as they look for the real content. Instead, refer to the policy. The idea being that once they read the policy, they can put it away and use it for reference as needed. The business requirements should support the policy and procedures. That is one validation you should do when reviewing the Business Requirements.
Your Table of Contents should tell you the big picture
Your table on contents should give the reader a pretty good idea of what is included in your project. If it doesn’t, it’s possible you need to reorganize your document and/or rename the sections to better describe it. With particular interest in a System Requirements document, the reader should not have to read it in its entirety to understand one particular component of the project. The System Requirements should be used a reference, not a novel. Take particular care in making sure references are made to other sections if you find it necessary to create more than one section for a component or if there is a crossover of functionality.
Write for busy people
If I am really busy and pulled in many directions I am less likely to focus on a document that rambles on and is poorly organized. Use bullet point when possible with smaller chunks of narrative for clarification if needed. Remember, the table of contents should outline your project. If it’s well done, the reader can review the areas important for them. Also, if the reader must review the entire document, it will be easier to review in sections without losing the context of what they are reading.
Create flexibility in your templates
Templates are great! They can help in creating repeatable processes for your organization. However, if they are too rigid you will find the writer trying to make-up content for a particular section even if it doesn’t apply to the project. This tends to create redundancy and babbling that ready like me hate. Remind the writers that the template is a guide, not a rule. If you can’t come up with relevant unique content for a particular section of the document, it probably is not needed. Take it out! Your readers will be grateful.
The bottom line? I am busy and so are my business partners. Don’t waste our time. If you can do that, you have created a successful, useful document.are