Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.

As Good As It Gets: Why Better Trumps Best

by Riona MacNamara

Quality, what is it?

Riona’s favorite interview question is, “You’ve done these docs. How do you know if they are any good?” This can often lead to a conversation about statistics or support cases, etc. Sometimes this is a hard question to answer. A big challenge is that don’t have a common vocabulary for discussing quality.

We need to establish this vocabulary. This will help us to define guidelines on what we can deliver to meet these qualities we can now describe. This will be hard to unify because we write a wide range of documentation types. Can we really have a single vocabulary for it?

There are two kinds of quality. Structural quality and functional quality. Right now we operate in an “I know it When I see it” world. We need instead to be able to:

• understand documentation quality
• define requirements
• execute on those requirements
• measure success
• communicate value

To frame this conversation, Riona drew a lot of ideas from the language of software quality, which has become increasingly professionalized.

Structural Quality

Structural Quality describes what the documentation should be like. It answers the questions:

• Are the spelling and grammar correct?
• Does it comply with the style and usage guidelines?
• Does it use proper voice and tone?
• Is it well-organized?
• Is it easy to navigate?

Functional Quality

Functional Quality is the effectiveness of the documentation. A document with high Functional Quality achieves the specific goals it was set out achieve. Specifically, it:

• it does what it’s supposed to do.
• it satisfies the stated requirements.
• it accomplishes what it sets out to achieve for users, the product team or the business.

Functional quality often depends on structural quality, but functional is always more important

How do we do it?

1. Start with functional requirements

   These are defined by internal and external stakeholders and can be team and company level goals combined with user needs.

   Examples:

   • Grow adoption of a product or feature
   • Deflect support calls
   • Increase signups
   • Improve task completion

2. Execute on requirements

   Write the Docs!

3. Measure success

   1. Gather the right kind of quality data. Remember that structural quality data isn’t very persuasive. It won’t convince people a document is of quality. So gather functional data.

      Sentiment data: Sentiment is about happiness. We can gather information about whether people are happy with the work.

      • feedback widgets
      • surveys
      • stakeholder interviews
      • user studies

      Sentiment data is important data even if it is anecdotal or just an opinion. Stakeholders are reporting on the satisfaction with the docs.

   2. User Behavior. If the goal was to increase use of a feature, you can measure that.

4. Communicate impact and value

   Quality data can be used to make a strong case for quality documentation.

   Be careful here. This is where we have traditionally counted things like changes which measure acivity, not impact.

Ultimately our goals should not be the production of documentation, but the achievement of functional quality goals.