Defining Levels of Quality in Technical Documentation

I’ve been a technical communicator for over 18 years. With those years, comes experience in planning, writing, editing, and managing.

Of those, writing and editing are tasks I perform daily and instinctively.

Recently, while planning and estimating upcoming writing effort, I found myself needing to stipulate details about the level of quality of the documentation. Since documentation quality is something to which I subconsciously adhere, I didn’t really have that clearly defined in writing.

For the purpose of planning, though, project details must be clearly defined so that all team members are on the same page with regards to expectations. (And, if the current resources cannot meet the desired level of quality, sometimes we must make choices like adjusting the schedule, hiring more resource(s) or lowing the quality expectation. But I digress…)

So, how do you define document quality when it’s something you do subconsciously…?

You start by properly defining it and then use that definition for planning and estimating of the upcoming writing effort. And then that same definition can be reused for all future project planning.

I’ll be honest: I hold myself to high standards.  I take pride in doing a good job, and I like to produce quality documentation. In a perfect world, all documentation should exist at the highest quality…but time constraints don’t always permit that.

Regardless of the quality level, there are a few things I always strive to do:

  • Spell check is always run. Always.
  • Major deviations from formatting are corrected.
  • Legal disclaimer is always up to date. Another always.
  • Unless I’m under a time constraint, document changes are always listed somewhere to help guide the reader.
  • Time permitting, I typically review and make corrections to grammar errors in the content.

Now…getting back to that definition of the levels of quality I did…  I started with a simplistic (and high-level) definition from JoAnn T. Hackos (Managing Documentation Projects)…and then I further defined each of those levels.

QualityLevel 1 Quality – “Meets minimum standards”Quality

Document Organization Has been reviewed for coherency of information
Document Structure May be in place but document may not be complete (some areas may contain placeholders where information will be placed later) or specific sections may be excluded entirely (part of document produced as subset of complete document)
Formatting Correct according to template in use
Spell Check Has been performed
Legal Markings Trademark and copyright markings have been applied according to requirements
Disclaimer uses most up to date text
Grammar/Style Review and Corresponding Corrections Content has not been reviewed for grammar/style issues
Terminology An acronym list may be in place but all acronyms may not have been included and acronyms may not be defined throughout text
Document Change History If an update to an existing revision, changes to the document have been described in section or appendix
Illustrations Graphics/illustrations have not been reviewed for style issues

QualityLevel 2 Quality – “A good job”Quality

Document Organization Has been reviewed for coherency of information
Document Structure May be in place but document may not be complete (some areas may contain placeholders where information will be placed later)
Formatting Correct according to template in use
Spelling Review Has been performed
Legal Markings Trademark and copyright markings have been applied according to requirements
Disclaimer uses most up to date text
Grammar/Style Review and Corresponding Corrections Some or all content has not been reviewed for grammar/style issues
Terminology An acronym list may be in place but all acronyms may not have been included and acronyms may not be defined throughout text
Document Change History If an update to an existing revision, changes to the document have been described in section or appendix
Illustrations Some graphics/illustrations have been reviewed for style issues

QualityLevel 3 Quality – “Best we can do”Quality

Document Organization Has been reviewed for coherency of information
Document Structure Complete structure in place and document contains no placeholders and no sections have been excluded entirely
Formatting Correct according to template in use
Spelling Review Has been performed
Legal Markings Trademark and copyright markings have been applied according to requirements
Disclaimer uses most up to date text
Grammar/Style Review and Corresponding Corrections All content has been reviewed for grammar/style issues
Terminology An acronym list is in place in the document and all acronyms have been included
Document Change History If an update to an existing revision, changes to the document have been described in section or appendix
Illustrations All graphics/illustrations have been reviewed for major format deviations and for grammar corrections
Some or all graphics/illustrations are aligned to illustration style defined by template

There you have them…my levels of quality and ones that I typically adhere to subconsciously.

Knowing the definition of these will help others with whom I work better understand the level of quality the documentation content will follow and will set their expectations accordingly.
How do you define the levels of quality for documentation…?  (Or, are you like me, and is that something you rarely think about…?)

Icon pack by Icons8

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s