Writing Effective Documentation

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. You can look at the massive memory leaks from MSDN code as to why that is a bad idea. .

  Also do not supstitute documentation for a poor user interface. If the interface is bad and the user must read the documentation, it will not be used.

• 46:00 Reviewing Your Documentation

  You must have an editor for your documentation. They will help correct errors and see what you do not see. The majority of open source documents are barely more than drafts. All good writers have good editors. You cannot effectively edit your own material. You know what you meant to say and that makes it easy to skip typos, missing words, or confusing meanings.

• 47:49 Making Documentation Accessible
  

  “Welcoming people at whatever level they are, and patiently helping them move up to the next level, is how you build your community.” ~ Rich Bowen (Red Hat)

  Coming full circle to the initial story, make your software, your product, your hard work useable by other people. Password protection of documents prevents even approved users form best using your product.