Keeping documentation simple

In my presentations, I preach that keeping it simple is key to effective technical communication. It takes effort to read (you can write this on my gravestone: reading is work!), and the less you make someone work, the more effective the document will be.

However, keeping things simple is easier said than done. Taking a complex concept and explaining it in simple terms is a skill (and it keeps me employed as a technical writer). So what can you do to simplify concepts?

Well, here’s a few tips that might help you out!

Keep it high level

This particular tip comes with a caveat: “it depends.” (If you’re a DBA, you’ll recognize this as being “the standard DBA answer.”) Among other things, it depends on your target audience, and it depends on the type of document you’re writing.

Consider the audience. If you’re writing for peers, chances are that you’d be okay with including technical jargon or abbreviations that your colleagues will understand. But if you’re writing for managers, other departments, external customers, or anyone who doesn’t understand the technology that you see regularly, chances are that you will need to keep it high level.

Most of these people don’t want to see, and often aren’t interested in, detail. I once had a manager who was fond of saying “don’t tell me how to build the clock; just tell me what time it is!” In other words, just get to the point. Don’t get bogged down in the details. Unfortunately, this is a habit that I see all too often with technologists who feel that they need to include every single little detail. Chances are, it isn’t going to be read. Don’t do it!

It also depends on what kind of document you’re writing. If you’re writing, say, a glossary of terms, a systems administration manual, or a data governance document, then yes, things will need to be spelled out and defined clearly. But if you’re writing a step-by-step guide, a checklist, or a quick-reference manual, things need to be interpreted in a few minutes, possibly even seconds. For example, if I’m writing a step-by-step guide, my rule of thumb is, if an instruction cannot be followed in a few seconds, the instruction has failed, and it must be rewritten.

Good writing matters

I said in my previous article that you don’t necessarily have to have command of a language to be a technical communicator. At the same time, the better command you have of a language, the better your writing will be.

In my documentation presentation, I cite an example of why good grammar matters. Take these two sentences which basically say the same thing, but one is written in active voice, while the other is written in passive voice.

  • The boy mowed the lawn. (Active)
  • The lawn was mowed by the boy. (Passive)

Question: which sentence is easier to read? I’d say the active voice (and I’m sure many English teachers would agree).

There are many more examples, I’m sure, where good grammar makes a difference, makes things clearer, and contributes toward more efficient writing. Bottom line: if you write well, your documentation is better.

Stop saying “PLEASE!!!” (Avoid filler words)

One of my biggest technical writing pet peeves is using “please” in technical documentation. I’ve written about this before. You are NOT asking people for a favor, you are TELLING them to do something! “Please” is a filler word that not only takes up space unnecessarily, it is downright annoying to read.

“Please,” however is not the only filler word to avoid. I don’t have a comprehensive list of words to avoid, but off the top of my head, words such as “like,” “professional,” “extremely,” and so on should be avoided. The more words that are added, the more difficult it becomes to read.

Some other statements may not necessarily be fillers, but they might not add anything, either. My advice: if you’re trying to tighten up a sentence, eliminate unnecessary words. If the sentence reads well without them, leave them out.

Use illustrations and examples

The adage that “a picture is worth a thousand words” is true! An illustration often describes a concept much better than just words can.

Which of these instructions would you rather follow? Would you rather follow this…

(Source: https://www.realsimple.com/beauty-fashion/shoes-accessories/tie-necktie)

…or this?

(Source: https://steemit.com/fashion/@ighoboss/style-made-easy-tie-knotting)

Even if I’m looking up an instruction, if it includes an example, I will often refer to the example first, and not even bother with what’s written, unless I have to glean some information from the text.

Use headings

Let me ask a question. If I wrote this ‘blog article without any headings, would you want to read it? You’d likely see lots of black text paragraphs without any idea as to what each one is about. Headings provide an overview of each section and topic. They provide a reference that’s easy for the reader to find what they want. They can even determine how a document is structured. Long story short: headings make a document easier to reference.

Let someone else do it

No, I’m not saying this as a cop-out! We all have our strengths and weaknesses, and for many people, writing and communication might not be a strength. So why not let someone else do the documentation heavy lifting for you?

Even if you’re not the one doing the actual writing, you’re still an important part of the writing process. It’s called being an SME (Subject Matter Expert). You have valuable information that you want to pass along. The writer is your interpreter. The writer will refer to you for information. (S)he will likely be asking you a lot of questions, which very much makes you part of the documentation process. Even a conductor is playing an instrument; (s)he is playing the ensemble that (s)he is directing. Being an SME is the same principle; you’re directing someone to do the actual writing.

Summary

These are only a few suggestions toward making your documentation better. There are many more ideas that I didn’t even touch, and they would likely make this article much longer than it already is.

Good documentation is essential for any business, and can often prevent issues before they arise. Keeping it simple goes a long way in making your documentation efficient and easy to follow.

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 )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.