Why Does Writing Documentation Improve Software Projects Quality?
Published on • 6 minutes readDocumentation in the project is useless. Every comment and text will be outdated soon and become more misleading than useful. Writing is also a burden because it takes so much precious time.
Yet, every developer uses documentation in everyday work.
I reviewed hundreds of projects ranging from huge corporate solutions to small side projects, and most had little to no documentation. It made them difficult to maintain, and some were even impossible to run without support from one of the project authors.
Documentation is a crucial part of the software because it’s the first point of contact for your users or developers who use it. Open Source projects with no description will be doomed from the start because no one will bother to go through the codebase to understand what it does.
Planning documentation and creating processes for its creation is a part of software engineering, that should be as important for developers as writing the code or tests.
Why Do Developers Avoid Writing Documentation? #
The biggest misconception is that time spent on writing documentation is wasted time, and the team should rather focus on shipping new code or improving the codebase.
The agile manifesto advocates valuing "working software over comprehensive documentation" to ship quicker, but it doesn't mean that documentation is something not necessary for project success. The key should be to create as much documentation as necessary to onboard the codebase quickly and easily maintain the project.
It’s like creating a Tech Debt, the time spared, will be paid back while maintaining the project in the future. You can’t assume that a year from now you and your team will be able to remember how every mechanism works and what was the context of the decisions.
Developers also avoid writing documentation because it feels difficult for them. It’s treated as a separate skill from coding, and most developers don’t feel like capable writers. The truth is that writing is a crucial skill for Software Engineers because it’s a form of communication.
“A good idea is an orphan without effective communication”
To be a good developer means having good writing skills, and documentation is a great way to exercise concise and purposeful writing.
It’s true that writing documentation comes with a cost - It’s way harder to maintain documentation than the code, and it’s possible that some parts will get outdated. You can prevent that by introducing proper maintenance processes. I believe that documentation brings way more value than the costs of maintaining it.
What Are The 7 Advantages of Software Documentation? #
Some Time ago I posted a question on Twitter about the benefits of writing documentation. Apart from the benefits for the project quality, people pointed out that creating documentation helps improve writing skills in your team. It helps improve your async communication, which is beneficial for everyone.
It also allows understanding your product better in case of user-facing documentation.
📖 5 Underrated Benefits of Writing Documentation 📖
— Daniel Idaszak (@IdaszakDaniel) January 9, 2023
• Faster onboarding,
• Team resistant to member rotations,
• Easier debugging,
• Better alignment between teams,
• Knowledge is available 24/7.
What else?
1. Context of Changes #
The most important part of the documentation is the context of changes. You shouldn’t blindly describe the same things which can be understood from reading the code. Instead, you should respond to questions like:
-
Why was a particular change made?
-
Why did we decide to implement it like this?
-
What was the context of the decision driving this design?
One of the best places to keep the context of the changes is a decision log, which can be implemented by Architecture Decision Records.
2. Improving Knowledge Availability #
Every part of documentation acts as a resource that is available at all times. Everyone can check it 24/7, which is especially important when working with remote teams spread across time zones.
You can’t afford to allow one person to keep knowledge about some part of documentation to yourself, and share it only when it’s necessary. You will quickly run into issues where only one person is able to solve the problem you have.
3. Avoiding Knowledge Loss #
Similar to knowledge availability, another problem your team might face is knowledge loss. If a person is the only source of knowledge about a piece of the code, losing access to that knowledge might result in dire consequences.
It’s crucial to document the context of the changes because soon you might realize that no one knows why something was introduced to the codebase, the person introducing the changes is long gone, and no one knows how to resolve the issue.
4. Faster Onboarding #
Well-documented project is a project that is easier to onboard.
Having information about what the project is about, what conventions are used, and the context of decisions made is something that will speed up the onboarding process for every new team member. This way you can avoid long, unnecessary calls explaining the same things to every new person.
5. Better Alignment Between Teams #
If you have many teams in your organization, who use each other's codebases, documentation act as a main communication tool.
Having the context of changes explained can support another team in making similar decisions. Good documentation helps make projects more congruent by using similar conventions. It will also help make the project easier to onboard and use for each team.
6. Clearly Stated Goals #
Teams are more focused when their goals are clearly stated. It can result in reducing mistakes in the codebase and helping your team understand what you are building. You can use a Software Design Doc to achieve it. It’s also a great way to gather feedback and make sure that what you need is built correctly.
7. Processes Are Easier to Follow #
If all the processes are documented, it’s easier to avoid mistakes. It will be easier to learn them and follow them. It will be also easier to introduce the change to your team if it will be properly documented and the team understands how to follow it.
Summary #
There are no great projects that don't pay attention to documentation. It’s used in everyday work, and it’s a main resource for learning using any software. If you want to create high-quality software engineering projects you have to learn to create good documentation. If your goal is to maintain a project for a long time, then you can’t afford to cut corners and avoid writing documentation.
What is your experience with creating software documentation? #
Let me know your thoughts on Threads - @this.dev or Twitter - @IdaszakDaniel.
Tweet