Writing Effective Documentation

“There’s a particularly pernicious anti-pattern in documentation where tutorials are provided for free but the real documentation is only available for purchase.” ~ Jacob Kaplan-Moss BJ was recently consulting on a WordPress site and the theme documentation was password protected. “Really?” he thought. The client wanted specific plugins used on the demo that came with the theme. Several hours were wasted trying to figure out which plugins the demo used until he was able to contact the client for the password to obtain access to the documentation. In somewhat related news BJ also recently won Infragistics Ulimate License from another podcast. Wanting to start out ahead he found their documentation easily accessible online. So password protection for docs on a $100 product but easy access for docs on a $2,000 product. “If you want them to RTFM, make a better FM.” ~ Kathy Sierra Many open-source docs are lacking in content. When looking for details on the API all the documentation contains is how to install. Whereas others like Microsoft’s MSDN are verbose and troublesome to navigate. This week the guys discuss the different types of documentation and what should go into writing each. One of the best areas for a junior developer to gain experience is writing documentation as according to Will many senior developers are lacking in the skill. Episode Breakdown * 23:28 Why Write Software Documentation? You will be using your code in 6 months. Do you want to waste time getting into the headspace you had when writing it? Documenting your code and the process of writing it not only makes you a better technical writer but also a better coder. By documenting your code, writing informative commit message, and useful README.md files others will be able to use or contribute to your code. * 26:29 Know Your Audience Your audience may consist of technical users looking for detailed referrences in your documents or end users using your documents to assist in marketing, enhancing the company image or even reducing technical support costs. When writing for technical users make sure to include an overview with key files, functions and subroutines, variables and constants, and the overall structure of your code. Be sure to include API references as well as any 3rd party objects or associated entities used in your code. Alternatively you may be writing for non-technical end users. When doing so look at the reason for your documentation. You may be writing to assist in marketing, enhance the company image, or to help reduce technical support costs. Get a sense of your audience by looking for clues such as job titles, existing documents, or even interviewing potential users. * 34:10 Scope and Content for Different Documents Overview documents such a README.md files on GitHub and BitBucket provide a starting point for users looking to better understand your code. Next comes step-by-step tutorials. These are quick and easy demonstrations of your code. They provide a starting point for usage. The meat of the documentation are detailed guides. With these comprehensiveness is the goal. This is also where many docs fail but books pick up. API references provide information for all public APIs. This is not a how to for the API but a reference guide or dictionary of the arguments used in the API and function calls. Ruby on Rails has some great cookbooks such as Rails Recipes. Cookbooks are solutions to common problems and how to examples of tested code. Finally error messages are documentation. At a minimum give a reason for the error so the user can look up a solution. * 45:19 Auto-Generated Documentation Auto-generated documentation is great if used as a starting point for writing documentations but are not good documentation themselves.