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 GuideGetting Started
System Requirements
Installation Instructions
Licensing InformationUser Interface
Main Menu
Toolbars
Navigation PaneWorking with XYZ Software
Creating New Project
Code Sample
Importing Data
Editing Options
Saving and Exporting/Lunch ProjectsAdvanced Features
Customizing Preferences
Collaboration and Sharing
Keyboard ShortcutsTroubleshooting
Common Issues and Solutions
Error Messages
Contacting SupportAppendix
Glossary of Terms
Frequently Asked Questions
Additional ResourcesIntegrated 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