It’s not useful if it’s not readable!
Revisiting my list of what makes the most effective documentation, we finally arrive at readability. Document readability is a big issue when dealing with any technical documentation. Not because the people don’t know the subject; they do. It’s not like the people aren’t smart; they are. I’ve always thought of it as an issue of skill and practice. It takes years of practice and skill building to be an effective coder, why wouldn’t the same apply to writing effective documentation?
So, what do I mean by readability? What makes a document readable? Again I refer to Ol’ Webster…
-
read.a.ble/rē’də-bəl/Adjective
1. Easily read; legible: a readable typeface.
2. Pleasurable or interesting to read: a readable story.
Documents that are more readable have a higher chance of actually being used, and hence more useful. There are many ways to judge how readable a document is, and there are even formulas that will actually calculate a qualitative measure or readability. I don’t go to that extent, especially with technical documentation, but I definitely keep the espoused concepts in mind.
When I write documentation, I concentrate on these aspects: the Visual, the Written, and the Progression.
Visual Aspects
- White Space – Don’t clutter up the page so the eye can’t follow what’s going on.
- Typeface – Does the font look appropriate, locks our eyes to the document and prevents eye-strain?
- Pictures/Diagrams – Always worth a thousand (or so) words.
- Lists/Tables – Helps group information so that the brain can easily identify and filter it.
Written Aspects
- Varied Sentence Structure – Mixed sentence structure forces the user to do a little exercise and concentrate on the subject matter. Otherwise it could be Sleepville for the reader.
- Define Words/Phrases – Uncommon phrases, abbreviations and jargon can quickly lose the audience. Include the audience by explaining what things mean: Don’t assume the audience has the same insider information or background you do.
- Step-by-step Procedures – Technical documentation, by its nature, revolves around procedures and processes. Proven, repeatable step-by-step guides can be the most cost effective way to capture corporate knowledge and pass it on. This pays dividends in the long run!
Progression Aspects
-
Generic to Specific Detail– The first few pages of the document should be written for management. And as the document progresses, more and more details is presented. The general progression I like to follow is:
Executive Summary -> Management Overview -> Architectural Design -> User Procedures
- Easy to Difficult Concepts – Each section of the document, regardless of the purpose, should start with the easy, big-picture concepts and slowly gather more complexity. Jumping right into the meat of the detail could easily leave the audience wondering what is being discussed.
As you write the documentation the organization needs to retain knowledge, a couple of….
Things to Avoid
-
Complicated Phraseology
“Moving forward, we will leverage our core competencies in emergent adjacencies to generate adaptable business revenues.”
Man; that’s awfully complicated! Can you imagine a whole document written this way?!?? If I were to put this idea in a readable format it would look something like…
“We will start searching for opportunities outside our normal business.”
Basically says the same thing…And I don’t have brain damage.
-
Overly Busy Graphs/Diagrams
I helped create this mess and can’t tell what the heck it says!?!??!!
Sometimes less is more…You could easily lose half of the content and still communicate the same ideas.
Well, it’s obvious that some of the items discussed here need a more detailed treatment, so I will add them to the list of my planned postings. Until then remember:
“The spoken word is captured by Time; the written word transcends Time.”