Good Documentation

Documentation is a view of reality. An idea, a perception, an image of something real. Documentation claims to represent reality.

But reality is subjective. Everybody has its own view of reality, and that may be wrong in some aspects. Furthermore this view mostly is expressed in an individual way. Wrong aspects and individual ways might make others misunderstand.

Documentation is communication. Communication is a premise for collaboration. Which made us the dominant beings on this planet. Did you ever notice that all things going wrong somehow can be explained by failed communication?

Whatever your documentation will be about, mind this:

• The Essence of Good Writing is Rewriting (William Zinsser)

There ain't no good writing without effort.

The following is about "good old" navigable documentation.
Wikis and Spaces are other concepts of knowledge / information preservation.

Hierarchical Structure

Structure enables us to quickly find what we are looking for, it enables navigation.

Imagine a book without a table of contents. You have to read all of it to find out whether there's something in it you are looking for!

Humans tend to think in hierarchies. A document's table of contents should be a hierarchy (tree), not a flat list. From the general to the specific. Or from the problem to the solution. Grouped by topic, by generalization, by term, by whatever.

The Magical Number Seven, Plus or Minus Two (psychology) says that the number of objects an average person can hold in working memory is about seven. There should be no more than seven child-chapters below a parent-chapter. More will be confusing, you might lose yourself. Less is fine (my favorite is two :-).

Imagine a collapsed tree where you can see only top-level titles. You find a trace of what you are looking for among those titles, you expand it, another trace - got it!
This is exactly how B trees work. And their speed depends on the number of possibilities on each tree level. Imagine that expanding the first title leads to 36 sub-chapters - would you like to navigate further?

Documentation is built from

1. words, built to
2. sentences, built to
3. paragraphs (untitled), built to
4. chapters (titled), built to
5. documents, built to
6. a bunch of related documents linked to each other

You could also adopt articles, sections, topics, short descriptions, headers, footers, foot notes, contents, indexes, ...
Look at specifications of document formats. The most mentionable is maybe DOCBOOK, but also DITA and of course HTML. They provide an abundance of structural elements.

Words

Good terms are the foundation of good documentation. They should be significant and concise, short but precise. They must be unambiguous at least in the scope of the document. Avoid using vague and all-purpose words that can be interpreted in many ways and are used in many contexts. Do not use buzzwords.

You must be aware that readers won't know your business terms. There should be term definitions on top of every documentation (unfortunately this mostly is a glossary at the end).
For example:

Term / Acronym	Synonyms	Explanation	Native Translation
Document	Writing, Article, Paper	A hierarchical knowledge representation in written form.	Dokument
Title	Header	The summary or abstract of the paragraphs below the title.	Überschrift

You will find out that writing such a table inspires a lot of ideas about the document to do. Terms are the backbone of the document. Forge them good and drop the too general ones.

The IT business really explodes from too general terms (it is The Tower of Babel:-)

• table ... do you talk about a database table? HTML table? Logarithm table? Oh, you mean our desk ...
• query ... you mean JS jQuery? Or CSS media query? A HTTP URL query? A database query?
• element ... you mean HTML elements? List elements? Chemical elements?

Order of Occurrence

It is important to not use a term before it was explained or defined.
When the reader comes across a word he/she doesn't know, he/she is forced to remember that word for later semantic binding. When unexplained terms begin to aggregate, the reader is overburdened and will perceive the document as exhausting and mysterious.

You surely know this from abbreviations. XYZ in every sentence, but never explained.

Sentences

A sentence has a certain structure, described by some human language grammar. Correctness of grammar will enable a common sense about the meaning of the sentence, which is a precondition for successful communication. Believe it or not, but there are sentences where a missing comma changes the meaning completely. Correct your misspellings and grammatical errors!

The longer and the more complex a sentence is, the less it will be understood by the reader, and the more errors will occur. Keep it simple, prefer short sentences.

Here come some wise recommendations from our rhetoric friends.

Replace passive expressions by active forms:

• Wrong: A concise name must be given to the method.
• Better: Give the method a concise name.

Use the verb to express the meaning, avoid "nominal-izations":

• Wrong: A call to init needs to be done after construction. (call = nomen)
• Better: You need to call init after construction. (call = verb)

Start the sentence with known facts from the past, and end it with what you want to point out and leads further:

• Wrong: Event-listeners are hard to control, because they are an one-to-many relation.
• Better: Because event-listeners are an one-to-many relation, they are hard to control.

A cite from The Elements of Style:

The surest way to arouse and hold the attention of the reader is by being specific, definite, and concrete. Great writers ... deal in particulars and report the details that matter. Their words call up concrete pictures.

Paragraphs

Paragraphs are layout, and layout matters. There must be visual breaks in the writing. Points where the spirit can take a breath. The worst document is one that has no empty lines, no chapter headings, no breaks, no place where all the things between the lines can evaporate, the endless word sausage :-).

Paragraphs are thoughts or facts expressed by maybe more than one sentence.

Do not copy & paste. Don't repeat yourself. The reader will start to skip paragraphs and maybe miss important points.

Use text attributes. Mark important words bold, technical terms italic, indent cites and examples, ... decorate your text to give the reader's eye a picture to remember.

Chapters

Chapters are one or more paragraphs that have a common title. This should abstract or summarize what's inside the chapter. The title will appear in the table of contents of the document and thus plays a navigational role.

Because everything inside a chapter is not known to navigation, a chapter should not be too long. The chapter is the book without table of contents you have to read entirely to find out what it contains.

Chapter is a recursive structure, it can contain other chapters.

Documents

Here we are at the root chapter. Writing good documents is not much different from writing good source code. The biggest sins are repetition of meaning and missing structure. "Reusable chapters" would facilitate recycling of the document at a later time.

Every document should have at least

• title
• author
• creation date

and optionally could have

• a state, like draft or final, maybe as list with dates, and
• a history of modifications, with date, author, and comment what it was about

It's nice to have a summary of the document, maybe at the beginning below the title. This should make clear what is inside, positively, and what won't be found here, negatively.

A document should contain photos, diagrams, drawings, whatever illustrates the text. But don't overdo this. An image is great, but a series of screen-shots can not replace a good description. Images contain a lot of informations, and the surrounding text must make clear which are the spots that matter, and what they express.

And last but not least a document should contain references / links to other documents. Best is to have these links in the chapters where their meaning for the document becomes clear by context (traditionally they are in a bottom list). It is important for a correct understanding of the document to name sources (versions, dates) that led to its assumptions and findings.

Summary

Good documentation is short, but long enough to be precise. The challenge is to learn how to rewrite in a way that enriches the document.