Most software engineers know that they should write documentation. But how many can articulate exactly why documentation is needed? Let's look into some of the reasons.
1. Productive engineers
The lack of good documentation is often cited by engineers as one of the main reasons holding them back doing good work. In 2014, 48% of Google engineers cited bad docs as #1 productivity issue, and the 2016 StackOverflow survey found that poor documentation was the #2 challenge at work for engineers
Engineers are not cheap. If you have 100 engineers, and you save them them 1 hour each month because you have decent documentation covering your internal systems, that translates into huge savings and a sizable productivity boost. If your engineers are wasting time searching for answers to questions that have already been answered, your velocity is going to suffer.
If however engineers document their work as they go, a lot of these interruptions can be minimized. Instead of asking coworkers for assistance, just check the docs. Need to setup a new development environment? Just check the docs. How do I deploy this project again? Just check the docs.
2. Remote employees will thank you
Over the past 2 years thanks to the Covid-19 pandemic, evern more of us have had to become familiar with working remotely. The importance of documentation is emphasized when you don't have coworkers around to answer questions when you get stuck. Now, you have to rely on asynchronous communication channels to get your answer.
You may send an email to that senior colleague, but when will they respond? Maybe they'll be online in Slack, or are they on a different continent and fast asleep? You may not get your answer for many hours and meanwhile you're stuck, unable to make progres. What's worse, soon a significant portion of engineering time is spent in these communication channels coordinating work instead of in the editor.
Having high quality documentation allows your remote employees to help themselves to get the information they need without interrupting a colleague's workflow, and stay productive.
3. Onboarding becomes a lot easier
Bringing on a new engineer is a big investment. It often takes months for an engineer to ramp up and become productive in a new company - every codebase is different and requires some getting used to. During those months they will be asking a lot of questions and taking time from other engineers.
Having good documentation can help here. Instead of having to sit down with other engineers all the time, the new hires can read through the documentation and become familiar with the codebase and customs on their own. Of course they won't be able to become 100% productive on their own. But you will be able to cut down their training time. And your new hire will thank you because they can be self-sufficient and don't have to feel like they are constantly interrupting their new colleagues to ask questions.
This is actually a great opportunity to test your documentation. If a new hire can get started on a project on their own by reading the docs, that's a great sign. If not, figure out what is missing, and make the necessary changes. Just don't make the new hire change the docs - that's your job!
4. Stop the brain drain
Have you ever been in a company with that one engineer who has been there forever? The one that knows every single system inside out and people constantly come to them to ask about different parts of the codebase. These types of engineers can be a liability.
The "lottery factor" (also known as the "bus factor") refers to the number of team members you could lose before your business stops functioning. Having critical information inside the heads of a small number of key people means that you are at risk of losing important institutional knowledge if they were to leave after winning the lottery, getting a better job offer, or simply deciding to retire.
By building a culture where information is written down and documented you maximize your lottery factor and stop the brain drain.
5. Encourage transparency
Writing in public encourages transparency. It's empowering to be able to see what other teams are working on and break down silos in organizations. Especially with remote teams where you can't have watercooler conversations, writing things down is not only important but absolutely necessary.
Engineers can go and look at how other teams are solving problems and even suggest improvements. It's a great way to share knowledge and make sure information doesn't get stuck.
It's cheaper than you'd expect
One common complaint about documentation is that "we don't have time to write things down" or "documentation isn't necessary". These are similar objections to what automated testing encountered a decade or two ago. Today, testing is part of any project's definition of done.
Documentation does not take a lot of time if done incrementally throughout the software engineering lifecycle. Similar to how taking a project with 0% test coverage to >50% is a huge effort, if you start documenting a project with no existing documentation, it can seem daunting. But small incremental updates and refactors are a great return on time invested.
We've written a post about how Google, Twitter, and Spotify built their documentation cultures if you're looking for tips on how to improve your organization's documentation. Here are some quick ideas to get you started:
- Use a docs-as-code approach to make it easier for developers to contribute documentation
- Start asking for documentation updates as part of code review
- Create "documentation days" where the whole engineering teams focuses on docs to bootstrap your projects with bad docs
- Provide templates your teams can use as starting points to start documenting projects
Top comments (0)