<Insert Graphic here> Use your imagination, WordPress won’t let me!
Of the four values from the manifesto for Agile software development, the one I hear most misrepresented by (mostly) non-agilists is working software over comprehensive documentation.
Frequently, it’s said with a grin, along with “I don’t have to document anything”. I’m generally polite enough to let people finish their sentence before emphasising the word “over”, over and over again until the meaning is understood.
So what’s wrong with documentation? From my experience, plenty! But there are also a few basic rules for all documentation (agile and non-agile) that would help no end.
Firstly, use a template. Every Company has a template. Maybe not for the specific document that you want to write, but a generic one will keep you on course. Use it. Don’t mess with the formats. That way the look and feel of your document will be the same as everyone is already used to, and your last document will look and feel the same as your first.
Secondly, language. It’s a business document; so write for a business audience, in plain and simple language. No contractions; its not a blog! Don’t show off with long words or complex sentences. Aim for something that anyone could read.
Thirdly, every document needs an introduction. Again in plain English, so that the reader knows the context and what’s coming, or whether they’re going to read it! It should be possible to pick up an individual document and using the first few sentences know where it fits in the Company/programme/project or organizational hierarchy, who the document is intended for, what brought it about, where is the connection to the bigger project or company need.
Then we get into readability. Be consistent with your use of terms; if it’s a “user” then keep with that, don’t flip-flop with other terms. Always write acronyms in full the first time they are used, regardless of how obvious you think they are! Include a Glossary and explain what these acronyms actually mean, not just what the letters stand for.
It’s not hard to write a good document, but it is easy to write an awful one.