2. Documentation Best Practices

While this article is about documenting source code, we are going to start off by observing that successful, high-quality Software Documentation and Source-Code Documentation have something very important in common: they both benefit from the strategies and tactics that apply to all successful documentation.

I call these strategies and tactics “Best Practices” because they are well known, successful methods for helping writers produce the highest quality documentation.

2.1. Purpose

The purpose of documentation is to enable the reader to achieve success with your product through gradiently-progressing understandings, while simultaneously quickly answering specific questions the reader may be asking.

2.2. Governing Principle

Like any product one is learning to use or manage that is complex enough to require documentation — software or for that matter, any type of product — that product’s success is strictly governed by the success it brings to its users, and how fast, and how easily that success is achieved.

2.3. What Is Documentation?

Documentation is written material that helps end users understand a product to the extent needed to competently use and maintain it, especially computer software or a machine.

That means, it has to carry that user from the knowledge he currently has, to the the knowledge required to competently use and maintain your product.

2.4. Qualities of Good Documentation

2.4.1. Obvious Qualities

Qualities that most everyone will agree with that good, high-quality documentation should have are:

Accessible:

The best documentation is easy to find and therefore quick to access. For readers that are computer users, that might mean that it is right at the reader’s finger tips (e.g. via a small number of clicks or keystrokes). For all readers, it might mean that there is an easy-to-use manual within reach where the reader works. (This is why automotive owner’s manuals are normally kept in the glove box.)

Clearly Written:

Any reader will not be able to grasp your intended meaning without:

  • presenting ideas the reader needs using clear, unambiguous language;

  • connecting what you are presenting with what the reader already knows; and

  • use of correct grammar for the language in use (a requirement for conveying clear meaning).

Answers Questions:

When a reader has a specific questions about the topic, that documentation can be used to quickly find the answers being sought. This is achieved by chapter and section titles being intuitive as well as being organized in a logical, progressive sequence.

Serves as a Reference:

Once the reader knows something is included in your documentation, he should be able to find it again quickly. This requires that each topic that is taken up is thoroughly covered in one place, and that where it is mentioned (in other places), duplication of material is minimized or eliminated by referring the reader to the one place where it is thoroughly covered.

Searchable:

Being able to find content in documentation can be enhanced by having a search mechanism available, such as:

  • electronic key-word and phrase search, and/or

  • an index (which is a manual key-word and phrase search mechanism).

Considers Its Audience:

First, know which of these common audiences you are writing for:

  • Users — want to use your product, and don’t care how it works.

  • Maintainers — want to be able to make it last a long time, and perhaps fix or enhance it.

  • Overhaulers — need to know everything about the product, as there is no telling to what extent they may need to dig into it.

Doesn’t Repeat:

A little repetition is okay, but a lot is a sign of needing to move detail to its one place in the reference section and provide a link to it instead of repeating.

Skimmable:

Ensure the plan for chapters and subsections is in logical sequence, and that titles are intuitive so that the material is skimmable. This helps the reader skip over concepts which he already understands or are not relevant to his immediate questions. Burying concepts in prose and verbiage demands more time from readers seeking answers to specific questions. Save your reader’s time by writing like a newspaper instead of a novel. Specifically:

  • Headings — should be descriptive and concise.

  • Hyperlinks — should surround words that describe the link itself (and never phrases like “click here” or “this page”).

  • Paragraphs and list items — should begin with identifiable concepts as early as possible.

Includes Examples:

When examples will empower the reader, include them. Many readers look first to examples for quick answers, so including them will help save these people time. Try to write examples for the most common use cases, but not for everything. Too many examples can make the documentation less skimmable. Also, consider separating examples and tutorials from more dense reference information to further help readers skim.

Consistent:

Be consistent in language and formatting: the more editors you have, the more important a style guide becomes in facilitating consistency. Consistency also helps make documentation skimmable and beautiful.

Current:

Keep it current. Consider incorrect documentation to be worse than missing documentation. When a product changes faster than its documentation, the users suffer. Keep it up to date. Make every effort to write content that is version-agnostic and thus in less need of maintenance. For example, generalize version numbers of software when they occur in tutorials (such as extracting a source code tarball with the version number in the file name). Some users will remain with older versions of your product, and thus require older versions of your documentation. Proper documentation platforms will accommodate such needs gracefully.

Discoverable:

Funnel users intuitively towards publications through all likely pathways.

Try to identify everywhere the user might go looking for documentation, and in all of those places, insert helpful pointers for them to find it. Documentation need not exist in all of these places, just pointers to it.

If a user manual is published in the woods, and no one is around to read it, does it exist? Discoverability says “no”.

Addressable:

Provide addresses to readers that link directly to content at a granular level.

The ability to reference specific sections deep within a body of documentation facilitates productive communication about the documentation, even with one’s self. These addresses can take the form of URLs, page numbers, or other forms depending on the publication medium. Readers may wish to bookmark certain sections, share them with other users, or provide feedback to the authors. The more granular this ability, and the easier it is to access, the better.

Uses a Gradient:

Content should be ordered to cover prerequisite concepts first.

Can a reader follow your entire body of documentation, linearly, from start to finish without getting confused? If so, the documentation’s gradient is perfect, which is great, but not always possible. It is something to strive for, especially in tutorials and examples. If you have separated your tutorials and examples from the reference documentation, then put the tutorials and examples first. Then, content within the reference information section may be ordered alphabetically or topically without regard to prerequisite needs.

The goal of gradient ordering is not to encourage readers to consume your documentation linearly — rather it is to help them narrow their search for information when filling in gaps in their knowledge. If a reader arrives with some knowledge of your product and begins reading the documentation at the 25% mark, they are likely to go to an earlier point when confused.

Complete:

Within each publication, cover concepts in full, or not at all.

Picture some documentation of software like a map of a neighborhood. If the map displays roads, readers will expect it to display all roads (which exist and are of the same type as those being displayed). Perhaps the map does not display railroads, for example. Thus, a reader approaching the map to look for railroads will find zero and then seek a different map — but the map is still “complete”, even with this shortcoming. “Complete” does not mean that the map must describe all characteristics of the land. It means simply that, for the characteristics it chooses to describe, it should describe all of them. A map that displays fifty out of one hundred fire hydrants in a neighborhood is worse than a map that displays none.

As a good example, iconv is a command line tool for working with character encodings. Its man page covers all of its available options but none of the possible character encodings accepted as values to these options. Instead, the man page instructs the user to run iconv -l to produce a list of character encodings. In this example, the man page and the list are separate publications, both of which are complete, which is good!

Publishing partially completed documentation must be done cautiously. To avoid misleading readers, make every effort to clearly state, up front, that a particular concept is only covered partially.

Beautiful:

Visual style should be intentional and aesthetically pleasing.

Aesthetics don’t matter to everyone — but (consciously or not) some readers will struggle to find comfort in documentation that lacks attention to visual style. Even in text-only documentation such as --help output, visual style is still present in the form of spacing and capitalization. If visual style is not important to you personally, then consider soliciting stylistic improvements from others for whom it is.

2.4.2. Not-So-Obvious Qualities

2.4.2.1. The Case for Sequence of Presentation

Sequence of Presentation is one of the most basic concepts involved in conveying ideas between humans, yet, for some reason, I find that this topic is difficult to find, and many writers do not use this in their writing. (See Articles on Sequence of Presentation.)

In my opinion, Microsoft’s documentation program has been failing BADLY since around 2003 because of this apparent omission in the training of writers.

Its governing principle is this:

Knowledge, to be able to be used by the reader, must be able to connect to knowledge the reader already has.

So what is the right sequence to present knowledge you are trying to teach? It depends on what your audience already knows. If that is a range of knowledge (which happens when you are writing to more than one person), then you will need to bring your least-knowledgeable reader forward, building upon what he already knows, establishing prerequisite understandings (basics), followed by more advanced understandings that build upon that knowledge, and so on.

If your least-knowledgeable reader might know nothing about your topic, then the place to start is always orientation.

2.4.2.1.1. Raising the Reader’s Awareness — Orientation

What is orientation? It is the process in which a person finds his position (in space and time) in relation to everything that is around or near him. In the context of documentation (i.e. learning and/or teaching), it is establishing answers to The Basic Questions including supplying applicable context, including how your product relates to other things he is (hopefully) already familiar with.

Imagine, if you will, waking up from a coma, and you did not recognize your surroundings and had no idea how you got there or how long you had been unconscious for. What stages does your awareness go through as you get back in control of your life?

Orientation MUST come first, or else all other new knowledge will have nothing to be connected to. The questions that need to be answered early from the coma scenario are:

  • Where am I?

  • How did I get here?

  • When did I get here?

  • What is the current date (i.e. how much time has gone by)?

  • Am I okay?

  • Are my family/friends okay?

  • What is in my immediate future, and who is involved?

  • What steps do I take from here to get back in control of my life?

2.4.2.1.1.1. The Basic Questions

Parallel to the coma scenario above, the questions that need to be answered early in orienting sections of documentation are:

  1. What is it?

  2. What does it do?

  3. Why does exist (i.e. what problem[s] does it solve)?

  4. How does it do it (overview level or via an easy-to-read diagram)?

Questions 1 and 2 should be answered, preferably, in the very first line of text that the reader sees when he finds and begins reading about your topic (or begins a new chapter, etc.).

Observe that on Unix and Linux systems, man pages (software user’s manuals) 99% of the time begin with answering those two questions on the very first line of text.

Examples:

Man Page

First Line of Text

man

man - an interface to the system reference manuals

ls

ls - list directory contents

cp

cp - copy files and directories

mv

mv - move (rename) files

sed

sed - stream editor for filtering and transforming text

gawk

gawk - pattern scanning and processing language

perl

perl - The Perl 5 language interpreter

Any person with experience with man pages recognizes immediately how important this is when learning how to use a new software tool — or looking for a software tool that helps solve a problem you are trying to address.

Questions 3 and 4 should be answered as soon as feasible after 1 and 2 are answered.

I believe you will find this is true for all successful documentation when the reader may know nothing about your topic or product when first encountering your documentation.

2.4.2.1.2. Raising the Reader’s Awareness — Understandings

After being oriented, the reader needs to acquire one understanding after another in a logical sequence, building upon what he already knows, establishing prerequisite understandings (basics), followed by more advanced understandings that build upon that knowledge, and so on.

Thus:

  • Basic (prerequisite) understandings come first.

  • More advanced understandings build on basics. It should be possible for the reader to start on one chapter about a given topic and cover pretty much everything about that topic, including an orientation to that topic at the beginning, followed by progressively more detailed knowledge, until he has it all.

2.4.2.1.3. Raising the Reader’s Awareness — Enlightenment

As the reader gains enough understandings, he begins to be competent with the topic you are presenting, and has realizations about what he can do with it, and what goals he can achieve by using it.

2.4.2.1.4. Layers

Observe that in teaching a complex topic that the reader will need to go through

  • orientation

  • understandings

  • enlightenment

over and over, once for each topic presented. This builds on itself from basics (prerequisite) topics, followed more advanced topics that build on those basics. Note that even advanced topics still begin with orienting the reader to that particular topic, and then bringing him through one understanding after another until he reaches enlightenment on (and therewith, the ability to use) that topic, and with observation, study and practice, gains competence in using it.

2.4.2.2. Learning Principle

This learning principle underlies important criteria for what makes documentation most helpful to its readers:

The mind is ready to learn what it is asking questions about.

Here are some questions that a writer needs to be asking himself to determine what needs to be written and how it should be organized. Some example answers are given, but it is expected that the specific topic you are writing about will have its own specific answers, and finding those answers will greatly help you to organize what you write and simultaneously ensure it is complete.

Q1: What questions is a reader going to be asking who is new to your product?

  • “Do I need this product (or tool)?”

  • “What would I use it for?”

  • “What problem(s) could I solve with it?”

Q2: Once he has decided to use your product, what questions will he be asking?

  • “How does it work?”

  • “How do I start putting it to work (unboxing, assembly, installation, etc.)?”

  • “How do I use it correctly according to its designer’s intentions?”

Q3: After he has learned to use it but is still a beginner, what questions will he be asking?

  • “How do I use it so that I am most efficient?”

Q4: And once he is an advanced user (and at the various points along the way while getting there), what questions will he be asking?

  • “How do I maintain it so that it has a long life?”

2.4.3. Sizes of Chapters, Sections and HTML Pages

It’s not the length of the web page, chapter or section that determines what is in it, but whether the reader can quickly locate and navigate to what he is looking for. If two concepts belong together, separating them into separate pages or chapters or sections (i.e. out of the reader’s view) merely for the sake of reducing the size of the page or section, can decrease usefulness of that documentation rather than increasing it. So when organizing or reorganizing your documentation, remember this: the ability of the reader to quickly locate and navigate to what he is looking for (e.g. via skimming) is more important than page size. Navigation panels in HTML pages can help immensely with this.

2.4.4. Summary

Good documentation provides a bridge for the reader to advance from the knowledge he already has, to being competent using and maintaining your product. Simultaneously, it answers your reader’s questions — where feasible — in roughly the same sequence he will ask them, while making it easy to find answers to questions that pop up due to the reader’s unique needs and experience.

2.5. Best Practices

So what are the best practices in writing documentation? Answer: whatever it takes to apply the above information so that your reader is able to study your documentation while remaining engaged throughout (i.e. continuing to learn and connect what he is studying to what he already knows), and thus achieve the purpose of that documentation: making the reader successful with your product through gradiently-progressing understandings, while simultaneously quickly answering specific questions the reader may be asking.