Rubrics are a scoring matrix (or framework, or simply a quality checklist) that you use to evaluate and score content based on various criteria.

• If documentation fulfills the criteria of the rubric, it’s likely the documentation is high quality and would rate well in user satisfaction surveys.
• If positive user satisfaction surveys don’t follow from fulfilling the rubric’s criteria, the rubric is likely misguided.

It can be difficult if somebody gives you a sample, and you’re looking at it for just a couple of minutes. Your eyes are naturally attracted to what you might call the shiny stuff, the visual impact. It may be harder to assess actually the quality of the writing, the information design, the flow of the information, that is the way in which has been written.

We recommend you use the same criteria that you would use if somebody was doing work within a team and you were giving it a quality check before it got published. One of the most common standards or criteria that people use within technical communication is to use quality criteria that was developed at IBM.

The quality criteria looks at a number of different factors:

Accuracy

• Freedom from mistake or error; adherence to fact or truth.
• Are there any mistakes in the steps that have been described?

Clarity

• Can people understand it the first time they read it?

Completeness

• The inclusion of all necessary parts, and only those parts.
• Is there the right amount of detail?

Concreteness

• The inclusion of appropriate examples, scenarios, similes, analogies, specific language, and graphics.
• Is there appropriate use of examples, for explaining terms that might not be familiar to somebody?

Organization

• A coherent arrangement of parts that makes sense to the user.
• Is it arranged in an order that makes sense for users?

Retrievability or findability

• Users can find specific items quickly and easily.
• Can somebody quickly find the information they’re looking for?

Style

• Correctness and appropriateness of writing conventions and of words and phrases.
• This can relate to plain English or clear English.

Task orientation

• A focus on helping users do tasks that are associated with a product or tool in relation to their jobs.
• Is it focused on the audience’s goal – what they want to achieve?

Visual effectiveness

• Attractiveness and enhanced meaning of information through the use of layout, illustrations, colour, typography, icons, and other graphical devices.

The eight rules of good documentation

Like good code, good documentation is difficult and time-consuming to write.

If useful documentation is so important to the success of projects and developer well-being, why don’t all projects have it? The answer, I believe, is that like good code, good documentation is difficult and time-consuming to write.

In my eyes, there are eight rules that we can follow to produce good documentation:

1. Write documentation that is inviting (conversational) and clear
2. Write documentation that is comprehensive, detailing all aspects of the project
3. Write documentation that is skimmable
4. Write documentation that offers examples of how to use the software
5. Write documentation that has repetition, when useful
6. Write documentation that is up-to-date
7. Write documentation that is easy to change and update
8. Write documentation that is easy to find and use