If we asked when we should write documentation, the probable answer would be “it’s not the best time, we have important things to deliver”. The problem with documentation is that it doesn’t bring immediate and easily measurable results. So how to fit it into the software development process in the best possible way? That mainly depends on the document type we want to write. It’s not always the same. If we do it right, we won’t lose too much time fixing the documentation afterward.
Conceptual documentation
To describe a general idea of the whole feature, part of the system, or a use case – it makes sense to do it after its implementation. If we do it before, we risk that the plan changes along the way, and we would have to amend the document too. But also we shouldn’t wait too long after finishing it, otherwise, we may switch the context, become busy with something else, and simply forget about different aspects of the feature. It makes sense to use the momentum.
The process of describing the solution could be embedded into the process. For instance, it could be the acceptance criteria of the story. Of course, it could cause tension. In that case, educating product managers and the team about the benefits of writing documentation makes sense.
API Docs
You won’t write the documentation for the whole API in one go. It’s a continuous effort. But in the context of a single user story, we could write a draft of the API design in advance as an outcome of the design process before starting the implementation. The benefit is that front-end teams can already mock some calls. Most likely the design won’t change significantly.
Design docs
It’s a part of the design phase. So it’s pretty clear that it happens before the actual implementation. It is way cheaper to describe the solution and verify if it makes sense and everyone understands it than if you implemented it all first.
After the implementation, there is no point in updating it. It catches the thinking process in a given time.
Release notes
This is a document that catches the outcome of a work period and summarizes the outcome. Therefore, it happens after the implementation and before the rollout. For example, before your mobile app is published in stores like Google play and app store, you submit release notes, the app is reviewed and then your users can see what’s been added to the newest app version. It doesn’t make too much sense to write release notes before the work because it should be accurate in capturing what has been done.
Testing scripts
You can describe steps to verify specific use cases of the system manually. Some companies may not yet have automated tests, which is a cheaper alternative. Some initial testing scripts could already be done by providing detailed acceptance criteria.
Later, we can discover more edge cases along the way. Over time, after the rollout, it can grow even more.
It can serve as an excellent reference point for people in the future doing code archeology. Of course, it also has a downside of describing a feature that may no longer be maintained and used which could cause even more confusion.
Postmortems
When something wrong happens with the system, the first thing we should do is to fix it. Afterward, when the dust settles, we can try to extract some learnings from the incident. Writing a postmortem helps analyze the situation step by step, and identify problems, procedural bottlenecks, and other issues. The idea is to learn as much as possible from it and prevent similar situations. It doesn’t make sense to wait too much before writing it.
It is not connected to the product development cycle.
Continuous Improvement
In many cases writing documentation is not a one-time act. When we try to explain a complex concept in simple words we find alternative explanations and gaps after the initial text is written. Therefore, we need to ensure that people know how to edit or at least report documentation issues.
When new people join the company. They bring a fresh perspective. During their onboarding, they are going to read a lot of existing documentation and that is also a good opportunity to challenge if they are complete enough.
When you hear a simpler explanation of the problem. It makes sense to update the docs with this explanation. Our goal is to explain things as simply as possible.
When the same question appears over and over. It could come from an engineering chat, or from customer support.
Verification
One of the documentation problems is that it becomes outdated after some time. It makes sense to occasionally verify if it’s still valid. Tools like Guru have a feature to periodically ask contributors to verify their cards.
We could also maintain the metadata ourselves. However, that requires more self-discipline, maybe even an agreed-upon process in the team. We could either update the documents on a regular cadence, or with a more ad-hoc approach, e.g. whenever we update the document, verify if it’s still up-to-date, and adjust the verification timestamp.
Engineering tutorials – write and execute
To spread knowledge within a team, people can do some things together. These can include some manual processes e.g. generating discount codes for customers, doing some operational work in the database, etc. We could persist the knowledge by first writing up the steps and then letting the other person execute based on that tutorial. The person going through the steps can identify gaps when the document is not clear enough and fix them along the way.
Company type
The state of documentation and the related processes can depend on the company type. If we take a fully remote company, most of the communication may be written in chats or in collaborative boards like e.g. Miro. If the company is asynchronous on top of that, even more of the communication is persistent. Things like solution design, explaining blockers, and writing up acceptance criteria. The documentation creates itself in a way.
If we take a small startup, that is still looking for the market fit, and employing only a few people, most of which are still the ones that are there from day one, we may not need that big documentation. The core knowledge is still in people’s heads, and it’s not clear if the company won’t change its direction soon. At this stage, there are more urgent topics to cover like e.g getting more customers.
The challenge is to find a good time to start settling down the knowledge and make it persistent. It may present itself when people start leaving the company (they take the knowledge with them), or when new people are hired (they need to get the knowledge). However, as mentioned before, each new hire is the potential to improve the documentation.
Summary
When you should write software documentation depends on what you need to write, and the company you work for.
- It makes sense to cover conceptual documentation as the memory is still fresh.
- For API docs, it’s good to cover them regularly as we develop new APIs. We could even write first drafts before implementation is done to unblock API consumers.
- Design docs should be written before the work and not updated afterward.
- Release notes are written to summarize the work that has been done so it doesn’t make sense to do it before the work.
- Testing scripts help to verify the feature and serve as a reference point to know what it should be doing.
- Postmortems are written after an incident. It doesn’t make sense to wait too long before writing it.
Updating documentation is a continuous effort. People should be able to easily edit docs or report issues at least. Newcomers often bring a fresh perspective and can identify gaps.
It also makes sense to write down the problem if it appears over and over again either between engineers or when it comes from customer support.
Documents can become outdated and it makes sense to have some metadata to know when it’s been last verified.
One idea to share and persist the knowledge is to let one person write a tutorial and let the second one execute it, and find potential gaps.
Remote and asynchronous companies produce documentation every day because of the way they work together.
Companies that are just starting may not need a huge knowledge base at this stage yet. But they need to be careful not to miss the point when they start to care about it. One such sign is when people leave or a lot of new people join.
