Greg Preaches: What Is Documentation For? How Should It Be Written?

Three weeks ago, I was at a Django NYC meet-up and the question of how extensive documentation should be came up. It was interesting because at time time, I was really beginning to pore over Amazon's AWS documentation, which turned out to be a royal pain in my ass. I expressed that during the discussion, and my experience with the AWS documentation influenced my opinion of documentation in general.

The Verdict

Documentation should teach the reader how to put each aspect of the application or API (or whatever) to work. Nothing about the text should be dense. All explanations should be put as simply as possible so that all ideas are clear. Documenting isn't story-writing (most of the time), so a reader should be able to read each segment in any order with little to no need to explore satelite segments.

When Does Documentation Suck?

Often, I look to code-related documentation because I don't know how to use a function, or I want to see if the API I'm working with is capable of doing something with or without much maneuvering. Ideally, the problem I'm faced with only requires a small explanation which can be written step-by-step. However, unless I'm working on something as simple as displaying a form on a web page or forking a subprocess, life won't be that easy for me.

Surprisingly, even something as simple as displaying a web form is hard to find good documentation on. Why is that?

Documentation sucks when what's written about the code/technology I'm using is vague; when it's clear that the author of the documentation assumes their audience is mostly comprised of Vulcans (a really smart race of humanoid aliens), the documentation sucks. If after reading I ask myself "Why would I need that?" you've failed to write good documentation.

What Should Be Covered

Inline Code Documenting

While I write code, I assume someone else is going to read what I wrote. I write a lot of Python code, and the language makes my intentions pretty clear. I don't need to write a lot of comments, but I normally end up with enough comments to write a short story about my application, depending on the number of lines of actual code I end up with, of course.

Inline documentation should:

  • clearly explain what each function and class (if any functions and classes) does.

  • be brief. Assume that those reading your code are pressed for time.

  • not rely on self-documenting syntactical aspects of the language you're writing the code in - e.g., intuitively-written code in Python and Ruby, which almost always looks clear while code purpose may be questionable when peered into deeply.

def __init__(self, app_filename, config_filename, model_filename):  
        #JSON file containing app info (app template)
        self.app_filename = app_filename  file (this will be the file we append models to)
        self.model_filename = model_filename 

        #JSON file containing field preset values and other info for parsing
        # the app info file
        self.config_filename = config_filename

        #store the app data as JSON text
        with open(self.app_filename) as json_data:
            self.app_data = json.load(json_data)

        #store the model field type presets as JSON 
        with open(self.config_filename) as config_data:
            self.model_field_types = json.load(config_data)['model_fields']
 file to write output to
        self.model_file = open(self.model_filename, "a")

"But Greg, that looks like shit! What are you doing? No, man -- you're such a noob for doing that."

Hold that thought.

Now, tell me why the above wouldn't be beneficial to me as the original coder and a person to whom this code is new. I bet you can't come up with a reason that isn't totally pompous and absolutely wrong. Go ahead - I'll wait.


'Non-Inline' Code Documentation

The documentation that stands on its own, outside of the code, should be more descriptive than the code it's clarifying. Still, what's written should be brief and shouldn't skew the reason the code exists. At no point should the description of an accompanying source or set of sources require a reader to read the actual code.

At all costs but that of brevity, the documentation should enable a reader to use whatever it is that's being documented based strictly on their understanding of the page of documentation they're using for help.

Of course, because we don't live in an ideal world, writing documentation that will solve every reader's problem is impossible. What's possible, however, is creating documentation that describes exactly the way code is meant to behave when invoked.

Examples of Great Documentation

The Linux Manpages - full examples galore; if you're writing C code, you're covered; if you're writing bash scripts, you're covered; there's very little need to consult other sources of help (like forums) because as long as you know the fundamentals of the languages the manpages cover, you'll be fine.

The Django Documentation - although there are some areas that need work because too much is assumed about the reader, the documentation manages to describe exactly the way each aspect of the API is supposed to behave; the "needs work" area: Django docuemntation fails to tie a lot of areas of its API together. To a beginner, that makes Django hell sometimes (personally).

Both the Django documentation and the Linux manpages share characteristics that make them stand out as model ways one should document what they're working on:

  • Each page contains brief descriptions of very specific areas.
  • Each description assumes the reader knows nothing of satelite areas of the technology/code being described.
  • There's clear order throughout the pages.
  • There's no clutter -- I don't feel overwhelmed.
  • Each page aims to teach, not simply describe and leave the user to figure out what's necessary in order to apply what else is in the description. The writers of both sets of documentation took time to write out applicable code to go with their very specific documentation.


Be brief.
Include code examples.
Assume little about the reader's expertise.
Also assume that the reader will be fired if they don't understand every aspect of your code/tech -- yes, that means you should consider the brevity of your documentation.
Be organized.

Renee, I miss you. I know you know. I'm set on seeing you graduate. You made me really proud.


Software Engineer

Subscribe to GregBlogs