Bad Documentation is a Killer

Share this article

Almost every developer has run into some bad documentation in their day. I can’t even remember how many times I’ve had to talk to a disgruntled tech support guy about an issue that should have been easy to find. Two of the companies I’ve worked with have even stopped using otherwise good software due to bad documentation. The challenge with documentation is that most developers really have no desire to write it. For those of us working on the web, we’ve had it easy because documentation hasn’t been critical for many web projects. Most of my clients don’t need instructions on how to navigate their sites or use the basic admin tools I provide. However, things have been changing. As websites and web-based tools have become more advanced, I’ve found myself working on more projects that require documentation. I’ve written documentation for external APIs and services, instructions for other developers on my team and tutorials for end-users. Most of my early attempts were unsuccessful and I ended up being the disgruntled support tech. To prevent this from happening to you; here are a few ideas to help make your documentation better and save you some time in the process. Know Your Audience Just like any other project, you need to know who you’re writing for. If you’re writing for tech-savvy end-users or other developers, you can usually cut out a certain amount of introductory content. Likewise, you don’t want to confuse average web surfers with details about how you handle complex data handling or memory allocation. If you find that you have separate groups of users, don’t be afraid to write multiple sets of documentation. It may seem daunting at first, but in many cases writing shorter, more concise documents for specific user groups takes less time than trying to make everybody happy with one. A good example is CMS vendors, most of the them provide separate documentation for developers, IT admins and end-users. Make use of Automated Tools Most languages have systems in place for automating documentation to some extent. Usually these systems don’t create anything good enough for end-users, but the documentation is usually right on target for other developers. In most languages, the tools generate documentation based on comments in your code. Integrating them is just a matter of changing your commenting style to fit what the documentation generator is expecting. I actually found that this provided the added benefit of making me write more consistent comments. Make Documentation a Community Effort Some of the most useful references for programming include a group of people. A completely user driven system, like a wiki, or a documentation system like the MSDN Library that allows users to attach content to existing article can both increase the effectiveness of the documentation and reduce the amount of effort required to maintain it. Wikis are also a great tool to use internally for preparing documentation. As you’re developing, it’s easy to add quick notes to the wiki then compile the content into documentation at release time. Even if it’s a system that is only editable by employees, it provides a central reference for workarounds, bugs and common pitfalls. Leave Time to Write Documentation Most of the disasters I’ve seen are the result of rushing through the process. It’s tough to cut a feature or push back a deadline to make time for documentation, but it will be worth it. Whether you end up with a tech support nightmare or spending weeks trying to get new developers up to speed, you will regret not spending the time to write things down. As web applications become more complex and web services and APIs become more wide spread, writing documentation is a skill that will become increasingly more important for developers. Hopefully these pointers will help you become a more effecient and effective documentation author.

Frequently Asked Questions (FAQs) about Bad Documentation

What are some common examples of bad documentation?

Bad documentation can take many forms. It could be a user manual that doesn’t explain how to use a product, a technical guide that’s filled with jargon and hard to understand, or a set of instructions that are out of date or incorrect. Other examples include documentation that’s poorly organized, lacks visuals to aid understanding, or doesn’t provide clear steps for troubleshooting common issues.

Why is bad documentation a problem?

Bad documentation can lead to a host of issues. It can frustrate users, leading to a poor user experience and potentially causing them to abandon a product or service. It can also lead to inefficiencies and errors, as people struggle to understand how to use a product or complete a task. In some cases, bad documentation can even lead to safety issues if it results in incorrect usage of a product.

How can I identify bad documentation?

Bad documentation often has certain telltale signs. It may be overly complex, filled with jargon, or lack clear, concise instructions. It may also be poorly organized, making it hard for users to find the information they need. Other signs of bad documentation include outdated or incorrect information, lack of visuals, and failure to address common user questions or issues.

What are the consequences of bad documentation for businesses?

For businesses, bad documentation can have serious consequences. It can lead to lost customers, as frustrated users abandon a product or service. It can also result in increased support costs, as users turn to customer service for help. In some cases, bad documentation can even lead to legal issues if it results in incorrect usage of a product.

How can I improve bad documentation?

Improving bad documentation involves several steps. First, identify the issues with the current documentation. This could involve user testing or feedback, or a review by a technical writer. Next, revise the documentation to address these issues. This could involve simplifying language, adding visuals, reorganizing content, or updating outdated information. Finally, test the revised documentation with users to ensure it meets their needs.

What role does a technical writer play in preventing bad documentation?

A technical writer plays a crucial role in preventing bad documentation. They are responsible for creating clear, concise, and user-friendly documentation that meets the needs of users. This involves understanding the product or service, the needs of the user, and the best ways to communicate complex information.

What are some best practices for creating good documentation?

Good documentation is clear, concise, and user-friendly. It uses simple language, is well-organized, and includes visuals to aid understanding. It also addresses common user questions and issues, and is regularly updated to ensure it remains accurate and relevant.

How does bad documentation impact user experience?

Bad documentation can significantly impact user experience. It can lead to frustration, confusion, and inefficiency, as users struggle to understand how to use a product or service. This can result in a negative perception of the product or service, and may cause users to abandon it altogether.

Can bad documentation be a safety issue?

Yes, in some cases, bad documentation can be a safety issue. If documentation for a product or service is unclear or incorrect, it could lead to misuse, which could potentially result in injury or harm.

How can user feedback help improve documentation?

User feedback is invaluable for improving documentation. It can help identify areas of confusion or difficulty, highlight missing information, and provide insights into how users are actually using a product or service. This feedback can then be used to revise and improve the documentation.

Ian MuirIan Muir
View Author
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week
Loading form