The State of Developer Experience Report 2024 by Atlassian provides a comprehensive look into the evolving landscape of developer experience, highlighting its critical role in developer satisfaction, productivity, and retention. As the complexity of software development increases, with the rise of AI and the prevalence of distributed teams, developers face significant challenges that hinder their ability to work efficiently.

The report, based on worldwide surveys of over 2,100 developers and engineering leaders, reveals a disconnect between leadership's awareness of these challenges and developers' actual experiences. Despite recognizing the importance of improving developer experience, many organizations struggle to implement effective solutions. One of the most pressing issues identified in the report is the role of documentation in developer productivity. 

This article explores the report's findings on documentation, providing insights into how platformOS developed and uses DocsKit to address these challenges.

We will focus on three key areas:

• Insufficient documentation —  a major contributor to developer time loss
• Cognitive load and the importance of accessible documentation
• Enhancing developer joy through better documentation

Insufficient documentation is a major contributor to developer time loss!

One of the report's key findings is that insufficient documentation significantly contributes to developer time loss. The research notes, "Our study found that the top contributors are technical debt, along with a lack of documentation, processes, focus time, and direction." Specifically, 41% of developers cited "insufficient documentation" as a significant area of time loss.

This highlights a pervasive issue: inadequate documentation frustrates developers and significantly drains productivity. When documentation is lacking, developers must spend valuable time searching for information or deciphering unclear processes, detracting from their ability to focus on planning, coding, and other high-impact tasks.

At platformOS, we recognized the critical importance of high-quality documentation early on and invested significantly in our developer documentation. Building on extensive user research and our experiences with developing our own documentation, we created the open-source platformOS DocsKit, an all-in-one documentation solution designed to help organizations build best-practice Docs as Code documentation sites that are user-friendly, accessible, and sustainable.

DocsKit includes a robust technical solution with a complete Docs as Code editorial workflow, various design themes, and supporting materials such as style guides and templates. DocsKit goes beyond traditional static site generators by integrating with any platformOS module, such as our video course module or community solution. Being a PaaS, it can be extended/customized without limitation. It can be hosted on major cloud platforms like AWS, Oracle, Google Cloud, and Azure — and upgraded to a dedicated stack as required.

Cognitive load and the importance of accessible documentation

The report further emphasizes the importance of documentation in managing cognitive load. It states that a positive developer experience is characterized by a "manageable cognitive load, thanks to well-organized code and easily accessible documentation." Additionally, "inefficient documentation is a major hindrance for 41% of developers in our survey. But that doesn’t mean that developers have the time or desire to write the documentation they need."

This dual challenge—needing high-quality documentation but lacking the time to create it—adds to the cognitive load on developers. When developers have to remember or constantly search for details that should be readily available through well-maintained documentation, their focus and productivity suffer.

Besides DocsKit substantially reducing time to market for deploying a best practice Docs as Code site, over time, we’ve carried out extensive user research to establish, adjust, and fine-tune the user experience. We designed DocsKit with an editorial workflow that is comprehensive and intuitive. It’s easy for developers and tech writers to use, as it integrates seamlessly with the familiar Git workflow and caters to other contributors through features that streamline the writing, reviewing, and editing processes — such as templates, linters, and AI-powered tools.

Our work on the documentation sites for the Washington DC Department of Buildings exemplifies our commitment to accessible documentation. This project highlights our dedication to ensuring accessibility and usability in documentation sites and demonstrates how DocsKit can be leveraged to create inclusive and effective documentation solutions.

Enhancing developer joy through better documentation

Atlassian’s "developer joy" initiative, as highlighted in the report, tracks satisfaction with documentation as a key component of the overall developer experience. The report states, "Drilling down into specific areas, we’re also tracking satisfaction with documentation and our cloud platform." This demonstrates a broader recognition that improving documentation is essential to enhancing developer satisfaction and productivity.

We are delighted to see that research on developer and user experience consistently underscores documentation's critical role. Much like the insights from various surveys we encountered last year, this research reaffirms our belief that documentation should never be an afterthought. Businesses must understand the profound impact that high-quality documentation can have on developer satisfaction, user experience, achieving marketing goals, reducing support costs, and overall productivity. High-quality documentation is a powerful tool that extends its benefits across multiple facets of an organization, driving efficiency, enhancing customer satisfaction, and supporting broader business objectives.

It’s reassuring to witness a growing number of businesses and organizations recognizing this and investing in their documentation, signaling a positive shift towards better support for developers and users across the industry. 

Conclusion

In conclusion, the State of Developer Experience Report 2024 emphasizes the critical role of documentation in developer productivity and satisfaction. Addressing the challenges of inadequate documentation is essential for navigating the complexities of modern software development. DocsKit is designed to meet these challenges head-on, offering a robust solution that improves documentation quality, integrates seamlessly into developer workflows, and enhances the overall developer experience. By reducing cognitive load and minimizing inefficiencies, DocsKit empowers organizations to maximize their development teams' potential, fostering innovation and success in the age of AI.