Documentation is essential to any organization’s success, particularly for software development teams. However, creating and maintaining effective documentation can be a challenging task. This article will discuss the top issues with documentation, provide actionable strategies to overcome these hurdles, and offers example OKRs to achieve success.

1. Analytics

Documentation may be fragmented across multiple tools, making it difficult to get a comprehensive view of engagement. Ideally, you would Integrate an analytics solution across all your documentation touchpoints and create a comprehensive picture of documentation activity and prioritize efforts accordingly.

Here are some strategies to tackle this challenge:

• Feedback Analytics: This involves collecting feedback from users on the quality and usefulness of your documentation. Feedback analytics can include feedback forms, surveys, user comments, and ratings on individual pages. This information can help you identify areas that require improvement and make informed decisions about which documentation to prioritize.
• Heat Mapping: This involves using a tool to track where users click and scroll on your documentation pages. This information can help you identify popular topics and areas where users may need help finding the information they need.
• Referral Tracking: This involves tracking where users come from when accessing your documentation. For example, you may track which search engines, knowledgebase systems, or portals are driving traffic to your documentation. This information can help you identify popular traffic sources and optimize your discovery efforts.
• Search Analytics: This involves tracking the keywords and phrases users search for within your documentation and the results returned. This information can help you identify popular topics and areas where users need help finding the information they need. You may also want to track search ranking to ensure the information developers need shows up first.
• Usage Analytics: This involves tracking the number of views and downloads of each piece of documentation and the time spent on each page. This information can help you identify popular documentation and areas that require improvement.

2. Ease of Maintenance

Maintaining documentation is also a common struggle. It can be cumbersome, difficult to keep updated, and inconsistent tooling. Here are some strategies to make documentation maintenance easier:

• Automate Site Creation: Provide simple methods for spinning up a new static documentation site with pre-populated templates.
• Automate Updates: When changes are made to the product or system, use automation to update documentation. This can include automatically updating screenshots, code samples, and other document elements.
• Documentation Management System: A document management system can make updating and maintaining documentation easier. It can also ensure consistency across different documents and provide version control.
• Dynamic Content: If you have an FAQ system like Stack Overflow, dynamically display FAQs for the tool or service inside the documentation. Whenever possible, pull from a single source of truth instead of creating redundant content.
• CMS: If you manage documentation inside the same repository as the code, consider ****implementing a documentation CMS such as the Netlify CMS.
• Easy Contributions: Reduce the barrier to updating documentation. If documentation lives in the repository, you have the beauty of version control and pull requests built-in.
• Templates, Guides, and Playbooks: By providing templates, guidelines, and tools that make documentation easier to create and update, teams can ensure that their documentation remains accurate and up-to-date.

3. Discoverability

Documentation may be fragmented across different tools, making it challenging for engineers to find what they need. Here are some strategies to improve discoverability:

• Bots: Train and integrate ChatBots in slack or other tooling trained on your documentation content to provide suggested answers to questions.
• Go Links: Go links are a URL shortener that allows you to create shortcuts to frequently used URLs. By providing go-links and other shortcuts, teams can help engineers find the documentation they need more quickly. Ensure you use a consistent naming convention for docs within go links such as go/toolname-docs.
• Documentation Portal: If your documentation is spread across multiple systems, rather than attempting to consolidate all documentation onto one system, you may need an abstract layer or data source to store documentation titles, links, and metadata.
• Error Message: Place ****suggested documentation inside relevant error messages.
• Repositories: Ensure your code repos contain the documentation or easy links to all relevant documentation in the README.
• SEO: Use descriptive and relevant keywords in your documentation titles, headings, and content. Provide metadata for your documentation pages, including title tags, meta descriptions, and other relevant information. This will make it easier for search engines to understand the content of your pages and make them more likely to appear in search results. This will help search engines understand your documentation and make it more likely to appear in search results.
• Search Inside Document: Ensure site-specific search is available, allowing users to search within each documentation site.
• Support Tickets: Create auto-responders based on recommended documentation based on support ticket context.
• Tools: Place documentation links in intuitive places inside the tools, such as under a “Help” menu in the UI.

4. Ownership

Identifying multiple owners for cross-functional documentation can be challenging, especially when it spans multiple teams. Here are some strategies to address this issue:

• Make ownership visible: To address this issue, teams need to evaluate ownership, make it more visible, and consider that documentation may have multiple owners responsible for small snippets or sections.
• Make it easy to transfer ownership: By creating a process for transferring ownership when a team member leaves or changes roles, teams can avoid abandoned documentation and ensure continuity. You can even write a bot to make it as quick and easy as possible.

5. Prioritization

Documentation is typically treated as an afterthought, and it can be challenging to get engineers to prioritize it. Here are some strategies to make documentation a priority:

• Clear expectations: Ensure everyone understands the importance of maintaining up-to-date documentation and what’s expected of them. Doing so will avoid misunderstandings and confusion and ensure everyone is on the same page.
• Culture: By establishing a culture of documentation, where engineers are encouraged to document their work and share their knowledge, teams can create a culture of continuous learning and improvement.
• Incentives: By providing incentives for documentation creation, such as recognition or rewards, teams can encourage engineers to prioritize it.
• Regular Reviews: Implementing regular reviews of documentation will help catch any errors or outdated information, making it easier to maintain accurate and valuable documentation. Regular reviews can help your team stay organized and prevent documentation backlogs.
• Institute “Writing Wednesdays” or doc-a-thons: Consider setting aside a day or a few hours per week or having a big quarterly event for documentation-only tasks. This approach will help ensure that the team has the time to focus on documentation.

6. Training

Provide training to improve writing skills, evangelize best practices, and remove blockers. Encourage engineers to practice documentation just like they would a technical skill. This approach will help your team enhance documentation skills and make them feel more confident about writing. Ideally, your training will include a hands-on activity where engineers are provided templates and apply best practices in technical writing.

Templates can help your team get started with documentation and make the process more efficient.

Example Template Sections

• Access and Authorization: Provide details about how to get access, permissions, and authorization to use the tool. If different roles and permission levels correspond to varying capabilities, note these roles in all places they apply.
• Architectural Diagram: Provide a diagram of the main components and how they interact to give users a glimpse of the whole.
• Code Samples: Provide code samples showing sample ways to call the tool, ideally in the user’s target language. This might mean providing multiple code samples.
• Conceptual Information: Provide information that answers the question of “why did you build this product this way?” and “what assumptions were made when making architectural decisions?” This can also include roadmaps for future features.
• FAQs: Provide answers to commonly asked questions intended to give customers quick solutions to their challenges and simplify their experience with the product. Ensure a consistent solution.
• Feedback Mechanism: Provide a way for users to provide feedback and suggestions for the tool in the form of an email, form, or support ticket.
• Getting Started: Provide a tutorial for users to get started in an end-to-end way with the product, producing a sample output that builds their confidence. This may include installation instructions.
• Glossary: Define unfamiliar words and jargon in a glossary. Ideally, your company has a glossary of jargon that can be used to auto-populate these pages based on tagging.
• Known Limitations: Provide a section called “Known Limitations” that notes pitfalls, traps, gaps, and gotchas to avoid.
• Overview: Provide a clear and concise explanation of what the tool does and its intended audience.
• Prerequisites Sections: Provide a “Prerequisites” section for each task that explains knowledge requirements, tool requirements, essential concepts, etc., necessary for completing the task.
• Resources: Provide links to recorded or upcoming training events, meetings, user groups, and Slack channels.
• Support Options: Provide options for contact or support, even if the support merely involves posting to a peer-monitored forum.
• Troubleshooting: Provide troubleshooting information indicating where things might go wrong and how to fix them, such as common error messages and debugging issues.
• Use Case Guides: Provide a guide or tutorial that helps customers understand why and how they would use a product to solve a specific problem they may commonly encounter across the company engineering ecosystem.

Note: You may want to start off with a proven documentation framework such as Diátaxis and use the Good Docs Project to select pre-made documentation templates in markdown.

7. Trust

If your documentation is outdated, inaccurate, or incomplete, it can lead to a loss of trust in your team’s work. Poor documentation has an exponentially negative impact on engineers’ time. Here are some strategies to build trust:

• Automating Notifications: Flag outdated documentation based on the date it was last updated compared to the date the code was last updated.
• Inventory: Take inventory of existing documents, match them against their ideals, and highlight gaps.
• Feedback Loop: Establish a feedback loop for documentation where users can suggest updates, flag outdated content or provide additional information.
• Standards: Establish standards for formatting, clarity, and completeness for a consistent approach to documentation. Spotlight engineers who model excellence as examples to foster a culture of continuous improvement.
• Checklists: Create a series of lists to provide guidance and ensure best practices.
• Documentation Health Score: Create a series of automated checks to auto-assign a documentation health score as an early indicator of potential issues.

8. Usability

The content can be accurate and up-to-date, but the documentation site itself can be cumbersome or difficult to navigate. Here are some strategies to improve usability:

• Accessibility: Use alt tags to describe the images on your website, making them more accessible to visually impaired users and search engines. Ensure your templates model excellence and accessibility best practices.
• Code in Code Blocks: Place all code samples in code blocks to distinguish them from the text.
• Concise Content: Ensure that sentences are short, paragraphs are relatively small, and subheadings are frequent. A readability score should place the content at the high-school level, not college.
• Consistent Navigation: Ensure that when a user clicks topics in the navigation, the UI doesn’t shift context in jarring ways, such as unexpectedly taking the user to another doc set or changing stable navigation areas like the sidebar and header (which should be consistent for every page).
• Consistent Pages: Ensure that common topics have similar names across doc sets in the developer portal. For example, the Overview, Getting Started, Troubleshooting, Glossary, Release Notes, and Reference are named consistently to help users understand how to navigate the site.
• Content Chunked: Organize the content into bite-sized chunks that flow well together. Use lists and bullet points to break up long paragraphs and make the information easier to read and understand.
• Descriptive Subheadings: Ensure that the subheadings are descriptive enough to allow users to get a gist of the topic by merely reading the subheadings. The subheadings should also follow a parallel structure to be more easily scanned and read.
• Grammar: Ensure that sentences are grammatically correct and read well without distracting the user or calling attention to the language.
• Indicators of Current Topic: Ensure that as the user navigates each topic, the sidebar navigation makes it clear where the user is in the navigation (for example, the topic highlights clearly, and the navigation sticks open at that level). Breadcrumbs also help establish site context.
• Keep it Simple: Ensure that the documentation focuses on the most straightforward path if there are multiple paths to a solution.
• Technical Level: Ensure that the documentation is written for a Level 3 Engineer who is familiar with the code language but has only been on Netflix for one day.
• Topic Summaries: Ensure that each topic usually has a short summary below the title that encapsulates the primary purpose of the topic. This helps users get a sense of the topic at a glance.