Search

Home > Complete Developer Podcast > Writing Effective Documentation
Podcast: Complete Developer Podcast
Episode:

Writing Effective Documentation
Category: Technology
Duration: 00:58:45
Publish Date: 2016-04-07 00:00:14
Description:

“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. 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.

IoTease

Since Will has trouble with soldering BJ found a great solution in a Kickstarter success story called Circuit Scribe. This is a conductive ink pen that writes silver ink on any surface. Experts can even solder to the ink.

Tricks of the Trade

Will talks about KISS (Keep It Simple Stupid). Don’t overcomplicate what doesn’t need to be complicated. Especially with configuration, it will prevent usage of your app or code. If you are going to have complicated config options have reasonable defaults so the average user can easily use your product. Always keep it as simple as possible but no simpler.

Editor’s Notes:
Total Play: 0