Documentation planning

J. Kelly Brito

People occasionally ask whether I can help their software development team improve their documentation. As with all consulting questions, I initially respond that it depends, and we should talk.

The rest of this article provides a checklist of questions for an initial discussion about software documentation. These questions should generate useful discussions that will identify challenges and uncertainties. Questions that you cannot answer correspond to uncertainty risk.

Contact me if you’d like to have an obligation-free documentation discussion.

Problems

First, think about which problem you want to solve.

1. Which of the following problems do you experience?

   • The documentation you have doesn’t deliver value
   • The documentation you’ve written costs too much effort to maintain
   • The team lacks experience with producing documentation
   • No-one wants to write and maintain documentation
   • You don’t have any documentation at all
2. How much management- or executive-level visibility do these problems have?
3. Has documentation become a political issue?

Goals

Next, identify which outcomes you want to achieve.

4. Which of the following do you aim to achieve with documentation?

   • Knowledge preservation, e.g. to mitigate the risk of people leaving
   • Efficient knowledge transfer, e.g. for new joiners
   • Collaboration with stakeholders outside the software team
   • Tangible deliverables or other proof of work
   • Legal compliance
   • Product differentiation
   • Marketing
5. How will you know if you have achieved these goals?
6. What happens if you don’t have this documentation?

Audience

Now focus on whose needs you would address.

7. Who will the documentation target? For example:

   • Internal developers
   • Management
   • Other internal stakeholders
   • Software users
   • Customers
   • Prospects
   • Technical partners and their developers, e.g. API users
8. How many people in which roles will read it?
9. How will they use it? When, and how often?
10. Are your teams co-located or distributed? Office-bound or remote?

Scope

Next, think about how to narrow the problem scope.

11. What do you intend to document, to start with?

    • Software design and implementation
    • Data models
    • Public APIs
    • Business rules
    • Business processes
12. How much of this documentation do you already have?
13. Which aspects of your existing documentation work? Which don’t?

Software system

Now consider the how the software to document affects the context.

14. How many years ago did the system go into production?
15. How many more years will its planned lifetime last?
16. How big is it?
17. Which aspects of the system exhibit above average complexity or complication?
18. How would you rate the system’s maintainability?

Budget

Finally, evaluate how much documentation you can have, and what quality level you can expect.

19. How many people, in which roles, can spend up to half an hour per week contributing to documentation?
20. How many of them have experience producing technical documentation?
21. How many of them want to write documentation?
22. How many of them can spend up to half a day per week?
23. Do you have budget to hire a full-time technical writer?