By Rochelle Fisher
Over the past 20 years, the definition of “quality” has evolved. Let’s take a look at what quality used to mean and what it means now.
The year is 1999. I delivered my first F1 Help project. On my desk was a bug report: “Explanations for the OK and Cancel buttons are missing.”
In a huff, I went to the QA engineer who wrote the report. I demanded in what I thought was a stern tone, but was probably more of a whine, “Why in the world do the users need to be told what OK and Cancel do?”
“You explained everything else,” said the young man calmly. “It looks odd that those two are missing from every page.”
My future-self guesses that the QA team probably had a quota of bugs to write, and this was filler. My then-self didn’t know this was a thing. She thought back to 1997, to her teacher’s words:
“The goal of technical writing is rapid information retrieval. We accomplish that through writing according to the three Cs: Comprehensive, concise, and consistent.”
As far as I knew, my writing was concise. It was consistent with my senior writer and with the style guide. If I added OK and Cancel, my document would be comprehensive.
Today, I believe that the definition of quality has changed. There are different ways to define quality. Let’s look at two: the ideal and the reality.
With the modern dispersion of technology, today no technical writer would waste time or space explaining OK or Cancel. In 2017, Jason Silva said, “A young kid in rural Africa with a smartphone has better communications technology than a head of state—than a president—had 25 years ago.” Our users have more knowledge, and less patience, than they had 20 years ago. If we waste our space with knowledge that can be assumed, we lose their trust that we have something to offer them. When users see something similar to “Click OK to close the window” in the first procedure, many will decide that the complete document is too remedial and close it. They will look for their answers in Google or open support tickets. Our work is undone.
If we upgrade our ideals of quality documentation, we can fulfill the vision of helping our users with rapid information retrieval. We evolve our definition of quality to meet the evolved requirements of our users.
- Rather than comprehensive, aim for relevant.
- Take concise and consistent to a new level with controlled.
- Expand our goals to include accountability by definition and make accurate an explicit characteristic of quality results.
If the product is basically intuitive, you do not need comprehensive documentation for every possible way to open a window or change a light bulb. If you know your target audience well enough, you can create product deliverables that answer questions that users ask. These questions can be anything from “What can this product do for me?” to “How do I respond to this emergency?” to anything in between.
Relevant is not a replacement for comprehensive. Quality documentation explains every feature; it is comprehensive. It also takes into account how much we explain and in what order. A comprehensive document explains everything that the developers give us. A relevant document explains what the user needs to know. Relevant technical writing is delivered in a medium that is expected by the users. It might not be a document at all. It could be video tutorials, self-service articles, or chatbot answers.
Let’s look at an example. In version 1.8 of a product, the admin guide mentions a new feature: Users are required to log in with Two Factor Authentication (2FA). We have all used 2FA, though not all of us know that name for it. It is when you are required to enter a code from a smartphone application, such as Google Authenticator, in a web user interface. In the 1.8 guide, the technical writer wrote more than 200 words about setting up 2FA with different vendors. Later, we realized that the admin who clicks 2FA Required on the product does not set up the authenticator. All those words explained what 2FA is and how it works. There was nothing for the user to do. In version 2.0, we made the documentation relevant. We replaced the 200 words with, “Users will get the QR code and instructions on their next log in to the Console.”
Be aware! If you give only instructions for what the user can do, your support engineers will complain. Users will open tickets to ask how something works, or what happens in the backend when an option is selected. You cannot make a hard-and-fast rule that your documentation will contain only what you think is relevant for the users until you learn what your users think is relevant.
Here are some tips that I use to write what is relevant.
- Use the product. If you write about using regular expressions (regex) in your product, be as knowledgeable in regex as your target audience. You will know what to document and how much. If you never use regex, you might end up hiding the relevant points in a mess of industry-standard knowledge.
- Build a relationship with your company’s professional services group (sometimes called customer success or similar names—the team who works with users, after pre-sales and before customer support). If possible, shadow an on-site visit.
- Lurk in webinars and lectures. Make a note of questions that are asked, and make sure that the documentation answers them.
- Take free, online courses in the field of your target audience. Make sure you know the terms and concepts that are assumed knowledge.
- Search for “this means that” and “in other words” in your document. These are red flags that you might have wasted words explaining the technology to yourself.
A concise document does not repeat information and does not use multiple words when one will do, but a document that conforms to a controlled language (CL) standard is, on average, 30% more concise than one written without a CL (Braster).
A consistent document might simply be consistent with a style guide, but a document written using a CL reaches a new level of consistency. The main purpose of a CL is to control the vocabulary. One word has one definition, and that definition is represented by that word only.
Even without a formal CL, you can control your language with a style guide, if it limits allowed grammatical forms and vocabulary.
Here is an example that offers more with less when the language is controlled.
- In the last step of the wizard, click Finish.
- When the install has been completed, restart the computer.
With a CL standard, this example becomes the following.
- Click Finish. One hour is necessary to complete installation.
- Restart the computer.
In this example, install is sometimes used as a noun and sometimes as a verb. This can cause confusion in longer sentences and for non-native English readers. The CL determines that install is a verb, and installation is a noun.
The original text tells the user when to start the action (when the last step of the wizard appears or when the installation is done), but the numbered steps indicate that the user should perform one action at a time. Why say, “When the previous action is done, do the next action,” when you can give information that is meaningful? Do not use the vague “when.” Tell how long the user must wait, or show the result, or remove that unnecessary text.
The best tip I can give for writing with a CL is to choose one (“Controlled Natural Language”), and then get professional training in how to use it.
I’ve seen many advertisements for technical writing courses that promote technical writing as something that ex-pats can “easily do” in a non-English speaking country or as a good part-time job for retirees of any background.
I cringe when I see these. Technical writing is no longer (if it ever was) simply writing. A quality technical writer is a tech lover, a fast learner, and a person who holds himself or herself accountable for the final deliverable. We cannot rely on others to do the technical work for us. We must run CLI commands. We must write scripts that use the API we are documenting. We must be hands-on. We must ask the questions that the users ask. We must get the most accurate information possible.
Here are some tips that I use to write what is accurate.
- Help QA when possible. If your company has a bug bash event, join it.
- Learn the operating systems that your users use. For example, if you learn enough Linux, you will know to add the dot before the slash if your SME forgets it.
Relevant, controlled, and accurate: these are the ideals to reach for. You can get training in a CL, learn your product line inside and out, and obtain an understanding of what the typical user needs. You can create quality deliverables given the time.
This brings us to the second definition of quality.
The reality of many companies is Agile sprints and frAgile releases. Quality is not an idea. It is a specific definition in the scope of a high-level work plan. Often, the definition of quality for documentation in this reality is, “it exists.”
We have our benchmarks, our idea of the perfect deliverable. We constantly strive for relevant, controlled, accurate results. It is good that we do so, but given two weeks to create documentation for a new product, we must become project managers. We get the scope and determine the priorities. We make impact plans and schedules for stages of delivery. We produce what is required according to the project plan and the product owner’s definition of done.
That is quality for that project. The definition of quality will change with the next sprint. Our ideal of quality guides us in our actual work, but it must never hinder us from fulfilling the definition of the project. We cannot let a release be late due to documentation. Sometimes, we must deliver a 100-word description of the product in concise, accurate language that is relevant for a specific vendor and that vendor’s audience.
And those 100 words will be all that we are allowed to deliver. And we have to be okay with that.
Braster, Berry. “HyperSTE – ASD STE-10 Software: Standardizing the Content of Technical Publications.” http://www.s1000d.ru/userforum/presentations/Day_2_Track2_01_Tedopres_HyperSTE.pdf.
“Controlled Natural Language.” Wikipedia. https://en.wikipedia.org/wiki/Controlled_natural_language.
Silva, Jason. Keynote Speech at Teradata Partners, 2017. https://youtu.be/7xGCmGt-yTo?t=376.
ROCHELLE FISHER (firstname.lastname@example.org) is a documentation team manager. She began her career in technical communication in 1997. Rochelle loves Simplified Technical English (STE) and has trained newbies in it, though she insists that a team who is serious about writing better, faster, and cheaper get some professional CL training.