Technical Documentation: Why So Technical?

Testing technical documentation often fails to explain the context, why the product works the way it does, and how it can truly benefit the user. Great testing documentation is both technically precise and easy to relate to.

We all start dealing with technical documentation without noticing it, either by consuming it (e.g. children reading instructions to assemble a Kinder Surprise toy) or by creating it (e.g. sharing that beloved banana cake recipe). However, the process of explaining a product or service so that anyone else can autonomously use it is far from easy.

As a technical documentation manager, I navigate the perennial challenge of making software documentation truly accessible. Documenting software products is always a challenge. In fact, writing any kind of instructions that will be helpful to others is a major challenge. Because we are not the users, we lack their exact experience and exact point of view, so we often miss context and meaning. Testing documentation often misses this mark, drowning users in technicalities without explaining the “why” behind the “how.” Testing documentation can, and should, be both technical and relatable. This article is about how we could help break down the walls of abstraction, making documentation not just useful, but also relatable and easier to understand.

Setting an Example

What better way to make things easier to understand than using examples? We've all done it, and we've seen others do it.
Testing documentation often lacks concrete examples, daily usage scenarios, and real-life stories. This isn't about adding another fancy section—it's about giving more soul and concrete meaning to documentation. We need to share experiences and methods that strip away unnecessary jargon, leaving users with a clear understanding of not just how things work, but why it matters to them. It’s not just about where you should click to start a testing session, but why you should use that button at all. It’s not just about saying we have a tool for exploratory testing that allows us to write a charter, but about explaining how you should write a charter and why it’s both important and helpful for you and your team members.

Testing and Documenting

The future (and present aspiration) of testing documentation lies in achieving a balance between technical accuracy and user relatability. Here’s how we can strive for this by incorporating concrete examples, relatable scenarios, and a stronger emphasis on the "why":

• Impactful: it should make a significant difference in how users interact with and understand the product. Impactful documentation doesn't just explain; it enhances the user's ability to utilize the product effectively. For instance, it can help users troubleshoot problems on their own, reducing dependency on support.
• True: accuracy is paramount. The documentation must reflect the current state of the product, including its latest updates and features. This requires a rigorous process of verification and validation to ensure all information is correct.
• Enjoyable: While "enjoyable" might seem like a stretch for technical documentation, it’s about making the reading experience as pleasant as possible. This means using clear, concise language, incorporating visuals where necessary, and structuring the content so that it is easy to navigate.
• Useful: It should provide real value to the user by answering common questions and solving frequent problems. Useful documentation anticipates user needs and addresses them proactively. It should cover a range of scenarios from basic operations to advanced troubleshooting.
• Reliable: Users need to trust that the documentation is a dependable resource. This reliability comes from consistency in content, thorough testing of procedures described, and prompt updates whenever the product changes.
• Functional: Documentation should be highly functional, meaning it is not just theoretical but offers practical, actionable information. Users should be able to follow steps and achieve their goals without confusion or errors.
• Answer the customer’s questions: The core purpose of any documentation is to answer the user’s questions, particularly “How do I?” This requires the documentation to be comprehensive, addressing every aspect of the product that a user might need to know about.

You can’t write any documentation, for testing products or not, without testing the products you’re writing about. How else can you guarantee it’s true, useful, and up-to-date?

Storytelling: The Useful Buzz Word

Writing is hard. Telling stories is an art. Making stories that stick with us is a gift.

And what’s experience and knowledge if you can’t share it and make it useful to others? One of the best ways to start a story is to tell a story about a real-life experience. We should try to apply this to testing technical documentation by:

• Making testing documentation technically sound yet relatable by having more concrete examples and the “whys” behind the “hows.”
• Highlighting the user journey: Illuminate the user's path by weaving relatable stories and scenarios into testing documentation.
• Demystifying technicalities: Break down complex jargon, providing clarity on technical aspects through simple, relatable explanations.

Storytelling is the most important aspect of any technical document. It’s the 3Cs: Coherent, Cogent, Comprehensive.

Inglorious but a Necessary Task

Documentation is one of the most neglected areas of software development. If a documentation page is useful, no one will thank you for it. If it’s bad, you will probably receive emails from unhappy readers. The work done by technical writers underpins several areas (Product, Engineering, Design, Customer Success, Sales, and Marketing): it explains the things that engineers develop. Sometimes it helps Sales and Marketing sell. It makes customers more successful and easier to support.

Conclusion

Technical documentation is a vital yet often overlooked component of software development. By striving to make it both technically accurate and easily relatable, we can bridge the gap between complex product functionalities and user comprehension. Through concrete examples, clear explanations, and a focus on the “why,” documentation can become a powerful tool for users, enhancing their experience and understanding. Storytelling, with its emphasis on coherence, cogency, and comprehensiveness, plays a crucial role in achieving this. Our aim as technical writers is to make the technical accessible, ensuring our documentation not only supports but also elevates the user's journey. In a constantly evolving industry, maintaining high standards in documentation is essential for the success and satisfaction of all stakeholders.