Credits:

• Photo credit: by Brett Jordan at Pexels

---

What makes a good technical document?

A good technical article, document, or topic has a few key points that make it stand out:

1. It understands the user and has empathy for the situation that brought them here, now.

   Don’t miss this point. It’s key.

   A good technical article has to be inside the mind of the user that’s come to the article.

   • What brought them here?
   • What is going on that has them stumped that they need to seek out help?
   • What are things that the user likely already knows if they are here for this topic?
   • What is the user likely to be missing if they have wound up needing this particular article?

   Depending on the type of article you are writing, you need to take into account the state of mind the user is in.

   Are they trying to implement or set up something? Are they on a troubleshooting page and probably have spent the last 30 minutes (or hours) doing steps on their own? Are they researching your tool to see if it might fit their need?

2. The article gives the right information.

   It’s really easy when writing to do a brain dump. “Here’s all the information I know about this topic!”

   But is that going to help the end user? No.

   The end user doesn’t need all of the information you have right this second. They need just the sliver to get them over the hump that has them stumped. Just the pertinent information that got them to put in their words in the search box and then select this article’s result.

3. The article gives complete information on its topic, and directs the reader to other topics that may be needed.

   This is along the lines of giving the right information. But it is more than just the right information, it is complete information.

   It is easy to fall into a trap of familiarity as a writer and assume that everyone knows what you know.

   Hint: they don’t.

   A good technical document does not make these kind of assumptions. Instead, it gives a complete set of information required to cover this topic.

4. The article speaks plainly, in good English (or whatever the language is).

   Good technical writers are aware of the jargon in their domain of knowledge, and they avoid it. No unexplained acronyms. No euphemisms. No favored glosses.

   Just regular words that someone completely new to the domain can read and understand.

Anyone can write

This is a prevailing belief I hear often.

Anyone can write.

There is a kernel of truth in it, of course. Many people alive today have benefited from education that includes reading and writing. Most come out of it able to write down letters that form meaningful words. They can string those words together into a meaningful sentence that provides communication from one person to another.

So, yes, anyone can write.

But not everyone can write within the bounds of the four points I made above.

So saying that anyone can write is a bit like saying anyone can play guitar. Sure, I can pick up a guitar, hold it in my hands, hold my fingers against some frets, and strum the strings. Being able to do these things does not mean that I can play the guitar well.

This is also true of writing. The vast majority of people have access to some tool and knowledge that allows them to write. But writing or typing out letters in sequences that make words, sentences, paragraphs, and articles is not sufficient for a good technical document.

What goes into good writing?

Many people are surprised to learn that good technical writing doesn’t involve nearly as much time writing as the title suggests.

Before I can come to the keyboard to hammer out a help topic, there is a lot of preparatory work that has to happen first.

• Research, both of the topic and the user who reads the article.
• Testing, to make sure that what is supposed to work does, in fact, work.
• Reporting bugs whenever something doesn’t work as it is intended.
• Interviewing people who have the knowledge.
  • Sales people, who are in the field the most.
  • Implementation, who have to make the system work for the buyer.
  • Support, who handle all of the questions from the customer.
  • Product manager/owner, who plans out just what is going to make up the product.
  • Developers (or equivalent), who actually make the product.
• Organizing the research into consumable information, such as by outlining.

Only after all these things are in place can the writing actually happen. And if all of the other steps have been done well, the writing can happen really quickly.

The problem with “good enough” docs

The problem with docs that are merely “good enough” to get people by is that they are always missing one of the key points above.

• They are not written plainly.
• They do not understand the needs of the user.
• They have not tested the product to make sure it can handle the use case.
• They assume too much of the user so that they have to chase down other information from elsewhere to make it make sense.
• They assume too little of the user so that they waste time scanning through information they already know.
• They answer the wrong question, or do not answer any question at all.

Any of these means that the end user, trying to get something done, spends too much time in the doc and comes away without the information they need to move on to their next task.

Good enough docs are never really good enough.

And, like Angelica Schuyler in Hamilton, we should never be satisfied with docs that are merely good enough.