Understanding Documentation

It’s tricky to get developers to write and maintain good documentation. Frequently, documentation has huge gaps in content, is woefully out of date, contradicts itself, or is simply impossible to navigate. Like writing code, putting together a useful set of documentation is not a natural talent, but is an acquired skill, usually built over long periods of time. Most of the time, the way you learn this stuff is either by screwing up, or by observing when other people screw up. Like your codebase, your documentation often has to be maintained, occasionally has to be refactored, and needs to be annotated well so that both you and your users can navigate it effectively. Further, you’ll have to make sure that your approach to documentation works well with a variety of use cases, plays nicely with the software development life cycle, and provides methods of feedback that help you make it better. Good documentation is almost a requirement for a serviceable product. Your users, support, marketing, and sales staff are going to rightfully expect that either your software is going to have decent documentation that stays up to date, or that they can bug you whenever they need you. In short, if you value your sanity, documentation should be your priority. Episode Breakdown Some reasonable base assumptions. Auto-generated documentation is almost useless, except for a few narrow cases. Outdated documentation is worse than useless. Documentation that can’t be navigated won’t be used. Having no feedback loop in your documentation is like not having error reporting. Consider your audience. There are lots of them. Other developers inside your organization need documentation to figure out how pieces of the system work. Management needs documentation so that they can explain things to their management and for planning. People looking to buy your software need documentation to determine whether it meets their needs. Your support staff need documentation so that they can troubleshoot common issues. QA needs documentation to make sure that software continues to meet specifications as expected by the user. Your actual users need documentation because they are using your software. If your documentation is online, it needs to be built with google in mind, because that’s the main way people will find solutions to their problems. People looking to integrate with your software need documentation to figure out the best way to integrate with your software and what value an integration might provide to their company. Potential business partners, or buyers of your company need to be able to look at documentation to figure out where your company’s strategy and theirs link up. Tech support people at other companies may need to read your documentation as well, especially if they are helping their own users troubleshoot. Your own salespeople may need your documentation to answer sales questions. People looking to get hired at your company may want your documentation so they can see if they would be a good fit. Consider your medium/media. The way you deal with content is different. Hyperlinked text is handy for relatively structured digging through documentation, but it can be annoying when trying to explain best practices or show something visually. Printed manuals. Some clients aren’t in environments where connecting to the internet is a good option. API documentation with samples. Other developers will need this to work with your systems. It may need to be tailored to a variety of programming languages in addition to human ones. Video documentation may be needed to show how to do common operations in your software so that you don’t have to train every single future user. Built-in help is useful for the user while they are in the application. It’s used to show how the screen they are looking ...