Internal documentation leads to better developer experiences—here’s how

In 2021, Google Cloud's DevOps Research and Assessment (DORA) team released its State of DevOps Report. In it, the research indicated that only one in four respondents could confidently say they had good-quality documentation in their organization. Meanwhile, the same report told us that teams with higher-quality documentation were 2.4 times more likely to experience better software delivery and operational performance. 

Any team that’s measuring developer experience (DevX) will tell you that developer efficiency and velocity are core attributes of a positive developer experience. Not having internal documentation that supports this speed and agility thus makes it harder for a team to deliver great DevX. 

This begs the question: why are teams not spending time and effort on their internal developer documentation? 

In this article, we’re articulating the value of internal documentation for teams that want to improve DevX and sharing best practices for how to implement a consistent process across the engineering team. 

What is internal documentation? 

For any given service, application, or API, internal documentation should give the reader updated information on how each element works and how developers can and should work with it. Internal documentation can look different from team to team, but it often includes details such as product requirements, internal infrastructure, architecture, development processes, source code, and FAQs. Ultimately, internal documentation should enable automatic and decentralized decision making, while also enabling developers to dive into working in a new environment. 

What is the cost of poor internal documentation?

As indicated by the 2021 State of DevOps Report referenced above, many engineering teams are lagging when it comes to creating high-quality internal documentation. These teams likely have a long list of reasons for not focusing on internal documentation: it takes too much time to get right, there’s no real incentive to write it, and there are so many other important things to do. 

The truth is, it’s far more costly to not be consistent with your internal documentation than it is to embed it into your day-to-day processes. Some of the challenges of a poor (or inexistent) internal documentation process include the following: 

• Onboarding is slow for new developers or existing team members working with a new API or service
• Knowledge gaps and silos means that developers have to spend time chasing down answers from other people
• People who leave their role don’t always pass on the information they know, leaving engineers to reinvent the wheel or cause problems 
• Developers stumbled across problems or breaks that could have been avoided with accurate documentation
• Decisions have to be stalled while team members find the information they need

Teams that have partially executed, low-quality documentation processes may have inconsistent processes for storing documentation, making it impossible to find. Plus, the documentation may be poorly written, not including the core components that are required to make them actionable. 

These challenges can all hinder the experience for both new and existing developers while also perpetuating a culture of disinterest and non-compliance when it comes to internal documentation. At the end of the day, developers understand the need for internal documentation, but they need to be empowered with the right processes and tools, as well as a collective effort to getting it right.

How internal documentation improves DevX

Done right, internal documentation should make it easy for a developer to be onboarded onto a new API or service. With comprehensive documentation that covers all the bases, a developer should be able to learn about a new system and start a new project without having to check in with other team members. Not only does this promote autonomy and independence—two factors that are crucial to positive developer experiences—it also mitigates knowledge gaps that can get in the way of scaling your operation. 

Good internal documentation should be: 

• Well organized and easy to navigate
• Complete, comprehensive, and up to date
• Free of any unnecessary information
• Supported with practical examples or useful context
• Clearly written in a consistent format 
• Frequently updated to account for any changes
• Include seamless search functionality so developers can find the information they need quickly

In 2021, GitHub shared data that showed that developers can be 50% more productive when documentation is up to date, detailed, reliable, and published in different formats. Great documentation helps developers save time, reduces friction as they take on new projects, and mitigates errors and misunderstandings. Ultimately, it enables developers to do more of the work they want to be doing.

The benefits don’t stop there. Great internal documentation also facilitates better decision making, ensures team members have the right information when they need it, and streamlines the onboarding process. This last one is important: the faster a developer is onboarded, the faster they can contribute to the codebase and provide business value.  

All of the benefits that stem from best-in-class internal documentation are inherently tied to improved DevX. As such, an investment in your internal documentation processes will ultimately lead to your developers having better experiences as they build their careers within your team.

Starting your internal documentation journey

For teams with lackluster internal documentation, it can feel like an insurmountable task to bring in best practices. Yes, there is a cultural shift that needs to happen, and a variety of new practices and standards to implement, but that doesn’t mean it has to happen all at once. You can take a phased approach to introducing new processes, tools, and standards, and each one will have a positive impact on performance and your DevX

As we mentioned above, prioritizing internal documentation will require a cultural shift. You’ll need executive buy in to move the project forward, as well as ambassadors within each department to help move the needle. There’s also an opportunity to gamify the rollout by getting teams to complete or update their documentation by X date as you build maturity in this capability. At the end of the day, you want your developers to voluntarily write and contribute to docs. 

Other useful steps include the following: 

• Make documentation easy. Use tools and templates that facilitate the creation of new documentation. Notion or Confluence can help here.
• Make documentation a core competency. To incentivize good documentation, you need to make it a requirement in professional reviews and hiring initiatives.
• Foster good documentation writing. Give people the opportunity to learn what it takes to write clear and easy to read documentation. Teach your leaders first and let them lead by example.
• Create documentation standards and checklists. Make it easy for developers to know whether or not they’re hitting the mark with their documentation.
• Share examples of good documentation. Use regular meetings or communications to showcase documentation that’s been done right. 

In addition to facilitating the process of documentation, it’s also important to invest in tools and systems that help make the internal documentation accessible and available. This way, you’re not just optimizing DevX in the creation of internal documentation, but also in its use. For example, as an internal developer platform that’s facilitating developer self-service, OpsLevel has technology and API docs piped in at the service level so that it’s easy to find information in context and in the moment. 

Documentation doesn’t need to be a burden

Internal documentation may feel like a tedious task to execute properly, and it can be, if it’s done poorly. As counterintuitive as it may seem, the teams that take the time to create robust and efficient internal documentation processes are the ones that can move faster and ultimately spend more time building new features and products. In addition, it’s a core function that can significantly improve a team’s DevX. 

At OpsLevel, 77% of customers use our IDP to drive an improved developer experience—and report being as much as 60% more efficient as a result. Learn more about how we’re doing just that by chatting with one of our specialists.