Figure out what’s wrong with your documentation.

Curiosity is a valuable trait for anyone who works on/with a team to achieve success. Most of you will want to ask what, how, and why things are not turning out as planned or as predicted. What could be going wrong? What should we be doing differently? This experience of curiosity is not different from what a technical writer faces when asked to figure out what’s wrong with documentation.

How do you give users what they want in your documentation, and how do you know something is wrong? To help figure out what might be wrong with the documentation, we need to draw a line to what type of documentation we refer to by giving specific information about the documentation in question.

You’d agree that documentation can vary greatly, from user manuals to technical guides, API documentation, and product documentation, and the issues can range from inaccuracies, clarity, and conciseness to formatting problems. This post talks about how you can figure out what’s wrong and the steps to take in tackling those issues generated from your documentation.

What could be wrong with your documentation?

Knowing what could be wrong with your documentation is one of the most critical steps toward growth and improving the documentation quality and effectiveness.

Building documentation without integrating means to gather feedback and review metrics from your readers is the basis for all things wrong with your documentation. Feedback helps you understand the impact of your documentation and the use of analytics tools to track user engagement.
Metrics like page views, search queries, bounce rates, and the time users spend on each documentation page are essential to publishing more comprehensive and effective documentation.

A high bounce rate or short time on a page may indicate that users need help finding what they need.

What to do: Conducting a survey, user testing, or direct communication with users. Pay attention to their comments and suggestions, as they can highlight confusion or dissatisfaction. Adopt the integration of analytic tools to monitor valuable metrics needed for documentation growth and effectiveness.

Knowing your documentation type

Here, I refer to the specific format or structure for creating and organizing documentation. Most organizations use DITA for their documentation. DITA is the Darwin Information Typing Architecture, and it is the go-to for easily reused, managed, and publication formats for various documentation.

Imagine a scenario where https:docs.xyz.com is a documentation assigned to you. Figure out what could be wrong with the documentation. Here is an example structure for our documentation:

URL: docs.xyz.com/user_guide
Title: User Guide for XYZ Software

• Introduction
  Overview of XYZ Software
  Defined Target Audience
  Defined Style Guide

• Getting Started
  System Requirements
  Installation Instructions
  Licensing Information

• User Interface
  Main Menu
  Toolbars
  Navigation Pane

• Working with XYZ Software
  Creating New Project
  Code Sample
  Importing Data
  Editing Options
  Saving and Exporting/Lunch Projects

• Advanced Features
  Customizing Preferences
  Collaboration and Sharing
  Keyboard Shortcuts

• Troubleshooting
  Common Issues and Solutions
  Error Messages
  Contacting Support

• Appendix
  Glossary of Terms
  Frequently Asked Questions
  Additional Resources

• Integrated tool
  Google Analytics
  Feedback Card
  Documentation Survey

Each topic is self-contained, written information to help with readers' needs, and topics can be reused/ referred to in a different section of the documentation.

What to do: Use metadata and structured content for easy organization, searching, and documentation customization.

Figure out what’s wrong.

Now, we conduct a content audit of the current documentation docs.xyz.com against our chosen style, i.e., Google developer style guide, to assess the relevance and accuracy of your documentation. Check for outdated or redundant content that you can rewrite for clarity. Also, ensure content conciseness and consistency, inclusive documentation for a more global audience, tone of voice, and knowing who is performing what action in the documentation.

Writing clear and bug-free code samples helps to improve the quality of your documentation and reduces time spent on trying to implement suggestive changes your documentation provides. Give your readers an insight into problem-solving with your documentation.

Here is what’s wrong with your documentation.

You have successfully conducted a survey, content audit, and user test about your documentation. Results gathered from those activities have to be constructed into a table form and prepared as a proposal to your manager about what’s wrong with the documentation by organizing a table of issues generated from the content audit and including the non-usage of third-party tools for documentation analysis.

With our created scenario, we have a structured documentation and integrated tool for generated feedback. What could be wrong with our documentation is caused by auditing our content using a Google style guide, checking for clarity of words, inclusiveness, and tone of voice. While writing, you should adhere to a global writing style.

Now, submit a proposal to your manager asking that somebody should work on these issues, give priority to them, and the expected time frame to get it done.

Conclusion

In summary, forming a documentation analysis is like figuring out what is wrong with your documentation which requires a careful consideration of the factors mentioned above. The quality of your analysis and the validity of your report