Bad Documentation is a Killer

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