Agile got (at least) one thing right: stop writing documents no one’s ever going to read. If you want to honestly assess what will or won’t be read – and therefore what should or shouldn’t be written – you should answer some basic questions.
We can divide these questions into two types:
1. Content questions: what you should write, based on the idea that it should match what people want to read.
2. Process questions: how you’ll write it, which affects the end result. Even if you have a genuine need for a document, if the process produces a different document to what you need, it might be useless.
The questions should include at least the following:
1. Is this just to cover me legally or is it intended to be read? If it’s a legal cover – write it, but keep it as short as possible.
2. Who do I think will read this? Why do I think they’ll read it?
3. What sort of information do they need? Do they all need the same information, or will some require far more than others? Should I write different documents to fit different users?
4. Will they value a long document, or would they prefer a very short one?
5. What’s the best way to get the information across? Could something other than written material work better?
6. Do I have enough access to a well-cooked version of the product to be able to write about it? Will I have to write some parts of it based on the design rather than the finished product? How will that affect the document’s quality?
7. Are several small documents better than one large document? Do they all have the same readers? Do I gain a lot of flexibility and quality from breaking the document down, or is the difference so small it may not be worth the bother? Can I release them one at a time or must they all be ready at once? How is the review process affected by breaking the document down?
8. Do I expect these documents to be useful for future versions? With or without editing? How does that affect the time I’m willing to spend on them and the way I write them?
9. Is this document intended for both external and internal use? Can I make it better for one use at the expense of the other, and do I want to (maybe two documents are better)?
10. Is the information that will make this document truly useful shareable, or does the document become useless once I remove all of the information I can’t reveal?
11. Is this document going to be used by the sales or marketing department? Does that require special consideration?
12. How do I want the document to be accessed, and does that affect how or what I write?
13. How many examples should I add? How much background? Is it more or less than I usually add, and can I really write in that style?
14. What other documents do I expect to need in the future, and how does that affect this document?
15. How much does this document improve on previous documents? Could editing the previous documents be easier and faster, without harming quality?
16. How much time do I really need, including the need to learn the material, wait for review cycles and perhaps leave time for a translation? How much time do I actually have? Will the document be ready in time for the version, or will I end up constantly behind the releases?
17. How many people will write the document? How many will review it? How does that affect the process and the final document (and its usability)?
18. How likely am I to need help? How likely am I to get it? Can I produce the document even if I don’t get the help I need? How much would that lower its quality?
When you know what you should and can write, you can decide whether or not it’s worth your time and effort. Avoid the temptation to write just to help pass the time or justify your salary; a better investment would be developing your writing or technical skills.