Struggles with providing proper documentation continue to be a weak point in many, if not most, software projects, which too often undermines the user’s experience. Sometimes, this even results in failed projects that could have had something valuable to offer in the worst cases.There are numerous reasons contributing to this situation. This includes the frequent lack of sufficient time and resources. Unfortunately, developers often wrongly assume that writing proper documentation isn’t their responsibility as they are primarily tasked with software development.Struggles with providing proper documentation continue to be a weak point in many, if not most, software projects. While at the very least this failing undermines the user’s experience, poor-quality documentation can cause projects to fail that otherwise had a lot of value to offer.There are numerous reasons for the dilemma. They include the frequent lack of sufficient time and resources. Sometimes developers think they don’t have the talent to properly document their pull requests and other work, when in fact the vast majority do. In many cases, developers assume their code is “self-documenting,” and must go back and figure out what they did when a support ticket comes their way about a feature a readme file could have easily explained.Worse still, developers might wrongly assume that writing proper documentation isn’t their responsibility as they are primarily tasked with software development.A “content specialist,” who might lack knowledge about software, could be assigned to the task, making claims about SEO expertise and other dubious skills but with little know-how to get the job done. On the other end of the spectrum, talented documentation specialists and tech writers and editors might be spread too thinly, earnestly striving to produce documentation but facing a scarcity of resources. They are often given the responsibility without the corresponding priority and contributions from those with the knowledge base in the organizations and the user and open source community to help. Consequently, software documentation often gets deprioritized and frequently lacks the necessary resources for accurate execution.As Kelsey Hightower emphasizes in the introduction of “Docs for Developers”: “If developers are the superheroes of the software industry, then the lack of documentation is our kryptonite,” Hightower writes.At the same time, for the developer, the most successful projects have documentation to guide developers through each workflow step, Hightower writes. “It’s because documentation is a feature,” Hightower writes. “In fact, it’s the first feature of your project most users interact with, because it’s the first thing we look for when trying to solve a problem.”In this article, we look at why proper documentation is critical and why it so often fails.Documentation is as “important as the code itself,” according to Alanna Burke, community manager and developer relations advocate, for Lagoon, an application delivery platform. For example, Burke described how a study with Cornell University revealed that 61% of professionals using distributed tools struggle to figure out their colleagues’ work. Additionally, 44% face challenges in identifying duplicated efforts due to siloed digital media tools, while 62% miss opportunities to collaborate effectively with coworkers.Burke highlights the significance of these statistics, as they shed light on the common excuses that lead to bad documentation practices. In many cases, some developers believe that code is self-documenting or find it too arduous to keep documentation up to date, impacting productivity. A Google case study revealed that 48% of their engineers considered poor documentation their top productivity issue, while 50% of Site Reliability Engineering (SRE) problems were attributed to documentation-related issues.Documentation is essential. Not done reading right, and the loss in productivity becomes very expensive. @aburke626 @Amazee #KubeCon2023 pic.twitter.com/b9RVM9Qutr— BC Gain (@bcamerongain) April 19, 2023The financial consequences of inadequate documentation are significant. IT professionals spend about 20% of their time searching for information, resulting in wasted resources, Burke noted. For an average salary of $60,000 per year, this translates to approximately $13,760 per employee annually. The opportunity cost, which reflects the potential earnings if time were not wasted, amounts to about $34,400 per employee, she said.“By recognizing the importance of documentation on par with code, organizations can make it an official part of every employee’s job description. Establishing this expectation fosters an intrinsic value for documentation, motivating individuals to update and disseminate information effectively,” Burke said.Burke emphasizes “the necessity of documenting everything as humans have limitations in data storage. Effective documentation should be easy to understand, devoid of excessive jargon, and complemented by relevant visuals,” Burke said. “It should provide clear instructions without delving into unnecessary details.”Additionally, documentation must be vetted for accuracy, with authors and dates specified to track any inaccuracies or updates, Burke said.“Burke said: ultimately, documentation empowers employees to grasp their work context, promotes collaboration, and encourages product adoption. Without clear documentation, organizations risk confusion, duplication of efforts, and inefficient data storage. Making documentation a priority ensures a seamless workflow and facilitates successful product usage and comprehension,”.Burke said, on the other hand, difficult-to-read documentation discourages users from spending significant time on it. To encourage user engagement, well-designed and interesting documentation is essential. Accuracy is of utmost importance, and inaccurate documentation can lead to significant issues. Google’s documentation practices include specifying the author and date, allowing easy identification of any inaccuracies and their origins. Furthermore, knowing the age of the documentation helps users understand its relevance and potential updates, Burke said.“This comprehensive approach to documentation ensures that users have all the necessary information to understand the code’s purpose, its origin, and any recent modifications made to it. By providing such clarity, we empower developers and users to work with the codebase more efficiently and effectively,” Burke said. “So, whenever you encounter a code block, rest assured that the documentation will guide you to its proper implementation, allowing for a smooth and well-informed coding experience.”Besides tailoring documentation to meet the needs of the users, getting there requires a team effort. The onerous might initially be on the developer to document code as they create code, but once that pull request is made, there should be an army of contributors ready to add their value input. Open source is also highly conducive for allowing the users to contribute directly.Among other things, good documentations requires input and collaboration from all stakeholders, especially the user, Fiona Peers Artiaga, director of documentation and technical writing at Grafana Labs, said during GrafanaCon.At Grafana Labs, commitment to documentation involves contributions from various sources, Fiona Peers Artiaga, director of documentation and technical writing at Grafana Labs, said. The team of contributors include the field engineering team, technical support team, and developers who collaboratively develop content, and especially, the users themselves, by way of direct feedback on the documentation pages on the website or via pull requests on GitHub, Artiaga said. It truly is a collaborative effort that is behind the creation of the Writer’s Toolkit, Artiaga said.“We value the input we receive from our contributors, so we develop our open source documentation in the open using a docs-as-code model,” Artiaga said. “This approach ensures that contributors can comment on the documentation, open issues, and improve the documentation themselves.”With good documentation, that 4:00 AM alert or urgent job ticket can be resolved by the user. The code is commented and READMEs are accurate and up to date in this case, Hightower writes. “You have a getting started guide and a set of tutorials that target your users’ top use cases. When a user asks you for help, you point them to documentation that’s genuinely helpful,” Hightower writes. “That four AM pager alert? It took five minutes to resolve because you found what you needed with your first search.”Consequently, software documentation often gets deprioritized and frequently lacks the necessary resources for accurate execution. Of course, it can also get overlooked in certain situations. For instance, a Content Specialist, who might lack knowledge about software, could be assigned to the task, making claims about SEO expertise and other dubious skills. On the other end of the spectrum, documentation specialists might be spread too thinly, earnestly striving to produce documentation but facing a scarcity of resources and often being given the responsibility without the corresponding priority and contributions from those with the knowledge base in the organizations and the user and open source community to help.As Kelsey Hightower emphasizes in the introduction of “Docs for Developers”: “If developers are the superheroes of the software industry, then the lack of documentation is our kryptonite,” Hightower writes.At the same time, for the developer, the most successful projects have documentation to guide developers through each workflow step, Hightower writes. “It’s because documentation is a feature,” Hightower writes. “In fact, it’s the first feature of your project most users interact with, because it’s the first thing we look for when trying to solve a problem.”In this article, we look at why documentation often fails and what can be done not only to improve the user experience when seeking help and support with documentation but in many cases, how otherwise great projects can be saved.According to Alanna Burke, Lagoon community manager and developer relations advocate, documentation is as “important as the code itself.” Burke makes this statement based on data and research. For example, a study with Cornell University found that 61% of professionals using distributed tools struggle to figure out their colleagues’ work. Additionally, 44% face challenges in identifying duplicated efforts due to siloed digital media tools, while 62% miss opportunities to collaborate effectively with coworkers.Burke highlights the significance of these statistics, as they shed light on the common excuses that lead to bad documentation practices. Some developers believe that code is self-documenting or find it too arduous to keep documentation up to date, impacting productivity. Google’s case study revealed that 48% of their engineers considered poor documentation their top productivity issue, while 50% of Site Reliability Engineering (SRE) problems were attributed to documentation-related issues.The consequences of inadequate documentation are significant. IT professionals spend about 20% of their time searching for information, resulting in wasted resources. For an average salary of $60,000 per year, this translates to approximately $13,760 per employee annually. The opportunity cost, which reflects the potential earnings if time were not wasted, amounts to about $34,400 per employee.“By recognizing the importance of documentation on par with code, organizations can make it an official part of every employee’s job description. Establishing this expectation fosters an intrinsic value for documentation, motivating individuals to update and disseminate information effectively,” Burke said.Burke emphasizes “the necessity of documenting everything as humans have limitations in data storage. Effective documentation should be easy to understand, devoid of excessive jargon, and complemented by relevant visuals,” Burke said. “It should provide clear instructions without delving into unnecessary details.”Additionally, documentation must be vetted for accuracy, with authors and dates specified to track any inaccuracies or updates, Burke said.Burke said: ultimately, documentation empowers employees to grasp their work context, promotes collaboration, and encourages product adoption. Without clear documentation, organizations risk confusion, duplication of efforts, and inefficient data storage. Making documentation a priority ensures a seamless workflow and facilitates successful product usage and comprehension.Burke emphasized that good documentation should be easily understandable and avoid excessive use of jargon or complicated language. It should be straightforward, getting to the point without telling unnecessary stories, and instead, focusing on providing clear instructions for users.According to Burke, incorporating good visuals in documentation is crucial as people are naturally drawn to pleasing and visually appealing content. Well-designed and laid-out documentation captures users’ attention and encourages them to engage with the material for longer periods, Burke said.Burke said, on the other hand, difficult-to-read documentation discourages users from spending significant time on it. To encourage user engagement, well-designed and interesting documentation is essential. Accuracy is of utmost importance, and inaccurate documentation can lead to significant issues. Google’s documentation practices include specifying the author and date, allowing easy identification of any inaccuracies and their origins. Furthermore, knowing the age of the documentation helps users understand its relevance and potential updates, Burke said.Addressing the right audience is another key aspect of effective documentation. Tailoring the content to the end users or administrators ensures that the information provided is relevant and meets their specific needs, Burke said.Burke highlights that well-crafted documentation is essential for seamless understanding, improved user engagement, and reliable information dissemination. By following these best practices, organizations can ensure that their documentation remains valuable and supportive of their users’ needs, Burke said.“One of my favorite aspects is ensuring that code blocks come with clear context, telling people where the code should be used. For instance, in this scenario, we have an application deployment Yaml file. In this example, users have a designated section to provide feedback, indicating whether the deputation was successful. Moreover, we go the extra mile by including essential details such as the author’s name, the date of the update, and a direct link to the corresponding Git commit.“This comprehensive approach to documentation ensures that users have all the necessary information to understand the code’s purpose, its origin, and any recent modifications made to it. By providing such clarity, we empower developers and users to work with the codebase more efficiently and effectively,” Burke said. “So, whenever you encounter a code block, rest assured that the documentation will guide you to its proper implementation, allowing for a smooth and well-informed coding experience.”Grafana Labs launched a Writers’ Toolkit announced last year during GrafanaCon. Fiona Peers Artiaga, director of documentation and technical writing at Grafana Labs said the toolkit is designed to empower all contributors to enhance documentation regardless of their role, whether from Grafana Labs or among the many global open-source contributors.It ensures the production of high-quality documentation by providing downloadable content, templates, and models. The toolkit offers writing guidance and templates, streamlining the process and reducing friction, thus helping contributors avoid common pitfalls that hinder others from finding technical solutions, Artiaga said.Artiaga said collaboration between those with in-depth knowledge of a feature and those skilled in presenting information is a core aspect. The toolkit promotes scalability by aiding contributors in creating technical documentation and objects, while also minimizing technical debt. It aligns closely with technical writing best practices and provides guidance and templates. When making a contribution, the technical writing team collaborates to ensure users receive the best possible information, Artiaga said.“At Grafana Labs, we want everyone to bring their gifts to the documentation. Engineers are best positioned to explain how the code works; technical writers are best positioned to create consistent, comprehensive, and consumable information,” Artiaga said.Key enhancements made in 2023 include improved navigation, recognizing that users search for information for various reasons such as problem-solving, answering questions, or gaining a deeper understanding of the tools used, Artiaga said. Diverse methods are employed, including search engines and navigating through different topics on the documentation site or starting from the docs homepage.Incorporation of more feedback into the design process is an active endeavor, Artiaga said. Increased interest and feedback from contributors help identify specific pages and topics they would like to see highlighted more prominently. This direct user connection is a source of enthusiasm for the writing team, Artiaga said.Moreover, the user context upon entering documentation has been enhanced. Recognizing that users often arrive from search engines, visual cues are provided to help them understand their location within the content and guide them to the next steps. Unlike the previous design, users are guided to primary topics and encouraged to stay within critical content, Artiaga said. A sidebar is thoughtfully designed to outline key subjects of interest and nest related topics underneath, creating a user-friendly ecosystem of documentation, Artiaga said.This is exemplified in the documentation for Grafana Tempo. By comparing the old and new designs side by side, the enhanced accessibility and focus on critical elements that make information easily findable and usable for users seeking answers are evident.At Grafana Labs, commitment to documentation involves contributions from various sources, including the field engineering team, technical support team, and developers who collaboratively develop content, and especially, the users themselves, by way of direct feedback on the documentation pages on the website or via pull requests on GitHub, Artiaga said. It truly is a collaborative effort that is behind the creation of the Writer’s Toolkit, Artiaga said.“We value the input we receive from our contributors, so we develop our open source documentation in the open using a docs-as-code model,” Artiaga said. “This approach ensures that contributors can comment on the documentation, open issues, and improve the documentation themselves.”Community created roadmaps, articles, resources and journeys fordevelopers to help you choose your path and grow in your career.