Writing down a few thoughts about documentation, as I realized a few things in the past two years that I did not write down yet, so here we go.
As software developers, we write documentation but we don’t often reflect on who is targeted by the documentation. Sometimes, it’s the end user that will read it, sometimes it’s a colleague from another team, sometimes it’s a non-technical person, sometimes it’s us in the future.
Depending on who is the most likely reader, we should adapt how we write. A user and/or non-technical person does not need internal or technical details about the system, but might need a glossary, a tutorial and non-technical vocabulary.
On the other end, for technical colleagues or for ourselves, we can probably skip the glossary, and we probably wants to dig deeper in details, because that is usually what matters most.
Related but not quite the same, the same user can come to your documentation multiple time with multiple needs. One time he needs a “getting started” section to get up to speed quickly, the time after he might want to find some “tutorial” to get going, and the next time he would look out for “references” documents to help dig further.
Same could apply for internal documentation, writing a tutorial vs a getting-started guide is not the same and should be treated differently.
This is more for the technical documentation, either architectural decision record, design document, or most technical document you can think of. This is also applicable for commit message (if using Git).
Giving context about the system or a change is probably one of the most important things to do.
If you give enough context (requirements, constraints, how the system behave at time of writing), other people should be able to understand why the solution made sense at that time. It is also a good idea to talk about alternative solution, why they were not chosen (a little list of pros/cons can help).
A picture is worth a thousand words. Use diagrams/schemas.
And if you do use diagram, please include the source of the diagram to make sure anybody can update it later.
We usually are reluctant to write documentation, but it is very rare in my experience that we write enough of it.
Something that can help you write documentation is Scott Hanselman’s take on keystrokes. Instead of responding on your messaging app or in a mail to one person asking a question, write a blog post or in a wiki or in whatever format make sense, then share it. Overtime, you should be able to link people to your posts instead of responding over and over to the same questions.
Yes. Documentation has a maintenance cost. Outdated documentation can even be dangerous because it can lead to false impression on a system.
But with a little discipline, and dating the documentation you write to easily spot text that was written a few years ago versus text written last week, that should not be a problem.
And frankly, it’s rare enough to have too much documentation anyway so this should not be a problem in most cases.
Some links to learn about documentation in various forms: