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:
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.
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
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.
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?
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.
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 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 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.
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
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.
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.
ɔ⃝ Fritz Ritzberger, 2014-11-17