How to Stop the Knowledge Loss and Support Writing Documentation
Published on • 5 minutes read
The way we work as software engineers is rapidly changing. Great resignation, layoffs, switching to remote work in different time zones.
I realized that the environment of the R&D projects I was leading was exactly like that.
When facing the issue of developers’ rotations and switching to async work, my two top concerns were knowledge availability and knowledge loss.
Although everyone knows how important it is to retain the knowledge in the team through documentation, teams still struggle to write proper docs.
I started wondering what I can do to help my team members and encourage them to start documenting their code.
Set The Expectations for Documentation #
First - as a leader, you need to set clear expectations.
When I started a project my main goal was to research new tools we could use in a commercial project, so my first task was to explain that.
To succeed we had to validate the tool and create some resources for the team to learn how to use it. We wanted the teams to onboard it quickly and provide value.
While setting the project goals such as the percentage of test code coverage you should already state that you are expecting proper README, key functionalities covered with documentation, database diagrams, ADRs, tricky cases, and everything you can think of.
Start With Why #
It might not be clear to the developer why are we doing that. Especially if you’re working with less experienced peers. If that’s the case, you should prove that documentation is not a waste of time.
Think about cases in the past where documentation saved your team, such experiences are setting the most powerful example.
For me, it was a case where complex app logic was broken and it was necessary to do time-consuming reverse engineering.
Prepare Guiding Questions #
If you are explaining the reasoning behind the docs' writing, you can also help them understand the purpose of a particular piece of documentation. You don’t want mismatched expectations. If you want an answer to some specific question - provide it.
Why is this document written? Does it include information on how the new code affects the codebase? Should research documentation include a recommendation on whether that’s a safe tool to use?
Explain How #
As a developer, I always struggled with deciding how to document my code. Most of the code is self-documenting, right? Isn’t adding a comment in the file making it a team’s responsibility to maintain my comment? Isn’t readme only for setup instructions? Aren’t docs only for product decisions?
Guide the developers on where should docs for a particular part of code live. Advise what form the documentation should take.
Provide Tools #
Make sure you have a proper README and a place to keep your docs.
Use tools such as TSDoc to make it easier to decide where a piece of documentation should be stored.
Add templates if you want a more formalized structure.
Create a wiki or document file for the team to create docs for more complex parts of your software.
Don’t let your team figure out what docs should look like and where to keep them. It will make the team struggle even more and waste precious time.
This is also a great moment to think about your audience. If that’s documentation only for developers, keep it in the repository. It will be easier to maintain and review through the existing code review process.
If that’s documentation that will be used by the product team and other stakeholders, the repository might not be the greatest place to access it. The same goes with user-facing documentation, maybe other tools would be more suitable?
Find The Time #
Another struggle that makes devs hate writing documentation is time. Creating docs is time-consuming and you should be aware of that. Give them space to do it well.
Think about how to manage the developers’ time to have a space for writing documentation. One of the ideas can be to include time for writing in an estimate. You can also create separate tickets to cover key areas with documentation.
Don’t let your developers feel miserable for taking the time to write docs.
Create Review Process #
If you want good documentation quality, you also need a review process.
If there is a proper code review process in place, why not use it for reviewing documentation?
Proofread your team documentation or let other developers do this for you. Asses whether a document is clear, concise, and complete.
Decent documentation will lower the cost of its maintenance in the future.
If the documentation is user-facing, then you need to have it checked by someone without your developers’ background. Make sure that the user is not stuck following your guidelines.
Create an adequate process for your team.
Lead By Example #
And the last thing, probably the most powerful of all the tips you can get is leading by example.
You can provide as much guidance, templates, tools, and other resources, but if you won’t create any documentation yourself, no one in the team will bother to make the project well documented.
Summary #
If you already did everything you could and there is no progress, remember that writing is not an easy skill to learn. For developers writing is usually a tedious task, treated as a burden rather than a possibility to learn.
I had cases where everything seemed prepared and explained, but the outcome wasn’t good. It’s hard to say what was at fault, whether it was developer motivation or time constraints. Sometimes just unredacted notes can be better than nothing.
What is your experience with helping developers to document software? #
Let me know your thoughts on Threads - @this.dev or Twitter - @IdaszakDaniel.
Tweet