Figure out what’s wrong with your documentation.
Tags: documentation, writing, community
Published: 2023-10-31 16:45:27

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 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