TW102: Pole Stars of Technical Content

Technical writing is guided by certain values. Like the Pole Star, if you let these values guide your writing, your writing will gradually improve until it rocks. Unfortunately, unlike the North Star, there are four of them in technical writing and they can often lead in contrary directions. Happily, striking the right balance is possible and will lead you in the right direction.

This topic isn't a guide to how to do all the things well. It's an overview of the things the things that your writing should embody. If you will, these are the somewhat abstract or relatively transcendental values of good writing. In my opinion. As always, I appreciate hearing yours.

Four pole stars

What are the polestars of technical writing? In my mind, they are:

  • Correctness
  • Clarity
  • Completeness
  • Concision

Let's take each in turn.

Correctness

This is the minimal standard for viable technical writing. It may be hard to be clear, it may be impracticable to be completely complete on a topic, and concision may be difficult in the circumstances, but it is better to write nothing than to write things that are false.

Incorrect documentation can:

  • lead users astray
  • do harm to your users
  • break down trust in your users
  • cause legal implications for your organization

Even small inaccuracies cause users to begin to doubt your expertise and to feel unsure that they are doing the right thing or even using their own time well.

Tips to ensure correctness:

  • Understand: Never pretend to document something you don't understand. Do not ape others' knowledge or act as a stenographer. You are responsible for understanding to the necessary extent the things that you document. Period. Learn the thing well. If you must document as you learn, then revise your documentation after you've finished learning.
  • Validate: When you find an answer in documentation internal to your company, confirm it. Internal documentation is notorious for not being well maintained.
  • Get validated: Get a subject-matter expert to confirm your facts and descriptions.
  • Get playtested: Get an educated but uninformed party, like a coworker, to playtest your writing. That means they read your overviews and intros, follow any steps, and ensure that it all goes according to plan.

A word about consistency. Consistency can be considered a kind of correctness because it involves setting up a standard for writing and then sticking to it. Observe the standard throughout your writing, your team's writing, and whenever possible, your enterprise's writing. Writing as consistent as useful with industry standards and it should generally be consistent with standard usage in the language used. Don't use commas in your own funky way. Don't adopt eccentric spellings beyond proprietary terms. Don't throw out random bits of formatting to make things "look better". Once you or your team has adopted a standard usage, your own, special-snowflake inconsistent case is incorrect unless you have a damn good reason.

Consistency improves readability and also findability. Technical writers strive to use words univocally. An essential practice is to use each word, especially terms that mean or may appear to mean something specific, in one way and in one way only. This is especially important for jargon and proprietary terms. If your company's product has a feature called a widget, do not occasionally call it a doodad. Technical writing is not the time or place for variety. You will only confuse readers. If you keep word choice, grammatical structure, and text formatting internally consistent and more or less consistent with usage outside your enterprise, readers will instinctively sense how you use them. This sense will then help readers use your table of contents, search bar, the CONTROL+F command, and other tools to find relevant information. If you "change things up" they will be lost. They will try to CONTROL+F the term that you used in one place, say, doodad, and miss your awesome explanation of doodads because when you decided to explain them at length, you called them widgets. Don't do that. Arrange your topics so they are consistent internally and amongst each other. Your users will be able to navigate within and between topics to find what they need. Unless all of your content fits into an easily scannable page, navigability is crucial for your user to have a good experience.

You should focus on consistency in:

  • Word choice
  • Grammatical usage and tone
  • Formatting and other presentation factors based on your medium

Your users won't thank you because they won't notice your consistency. That's the point: they'll trust you and find what they need.

Clarity

The reason for clarity is that your docs, no matter how correct or complete or concise, are useless without clarity. What's the point? Take time and do the hard work to make sure your docs are clear. Points to consider:

  • Who's your audience? I can explain APIs to a second grader. I've done it. It worked. But I did not give her the same explanation that I gave my company's Finance Controller. Does this mean that you try to write to both audiences? Not at all. Pick one. You can't do both. Be clear in your own mind and make it clear to anyone who crosses your document, "This doc is for me," or "This doc is not for me at all." A disclaimer at the top of a document is often useful: "To complete the tasks in this topic, you must have administrative privileges to Zoomdata."
  • Readability. Remember - we're not writing the great American novel here. We're writing to help people understand complicated topics and to complete tasks that they don't understand. Your writing should be a bridge, not a barrier. Until you get the hang of it, make a habit of testing your writing against readability scoring tools that provide good feedback. Aim for the 7th-to-10th-grade reading level. Readability is a measure of, among others:
  • word choice
  • sentence structure
  • sentence complexity
  • sentence length
  • Images or videos. Images and videos are powerful tools. But they are powerful for good and evil. They can save a thousand words, but also make it harder for people who can't see videos but could have listened to text-to-speech read to them or who could have read braille transcriptions. Additionally, videos run the risk of becoming dated if the product or service or task changes . I've had UX teammates flush dozens of hours of my work down the toilet by making our boxes have nice rounded edges after I made the video.

Completeness

Completeness is a more ambivalent term than may appear at first. I mean, there's complete, and then there's completely complete. If you've ever worked on a project that had to ship good enough then you have a sense of what I mean. Especially in an online publication, when we can often revisit a published topic and touch it up later, "good enough for now" is often as good as it gets. But there's another level of ambivalence and this one is much more essential to technical communication. I can't tell you everything and you don't have time or interest anyway. This key point ties into the dictum above. Know your audience. What does your intended and probable audience need to know when they look at your article. Mark Baker's book Every Page is Page One discusses this point: tell your audience all they need to know, but not more. Content should go elsewhere if it relevant but not immediately necessary to the topic at hand. That's what cross references are for. How do you evaluate the completeness of a topic?

Points to consider:

  • Have you covered prerequisites before beginning? Don't wait till the end of a topic to tell users what they need to know to get started understanding or acting on it. If prerequisites are complex or need explanation in their own right, list them at the top of your topic and use each item as a hyperlink to a fuller explanation elsewhere.
  • Have you raised questions without answering them? If the answer is long or complicated, and especially if it gets tangential, it's a good idea to discuss it more elsewhere so you can stay on-topic until you complete the current topic.
  • What are your assumptions about your reader? Answer the question on a macro level at the outset. Ask the question for each section of a topic or article. What does the overview assume the reader knows? What does each step of a task assume the reader knows or can do? Assumptions are OK. They can be good. We can function without them. Ensure your assumptions are sensible.
  • Do you have suggestions for further related reading or next steps? Technical content isn't like a novel in the sense of having a "The End." Technical writing only ends when the reader finishes reading. When the reader finishes with a topic, they often have other questions and sometimes need to continue to other tasks. Try to expect those and rather than answering them in the topic, where they are off-topic, provide links for further information. This is an especially good way to end most topics.

Concision

I once copyedited a text that started off, "Users have the option to select changes..." and I could only groan.

Users have the option to can select changes change...

Do you see what I did there? I reduced seven words to three. I cut out 57% of the words, but not 1% of the meaning. If you repeat the exercise on the scale of a book, you can save your reader from wading through tens of thousands of unnecessary words. And those words aren't trivial. They accumulate into a sense of vapidity or meaninglessness that frustrates a reader in a way that he or she can't quite articulate. Do not subject your readers to extra words. That kind of fluff - and there is no better word for it than fluff - might make you feel like your writing is official or important. They do not help your user do anything. Those words also become expensive if you need to print or translate your work.

As with the other pole stars, concision operates on many levels. There is conciseness of text, but there is also conciseness of the documentation set as a whole. Your reader's goal in reading your content is not to read hundreds of documents. It is to learn a concept, find a fact, or get help completing a task. Removing content that is very rarely used helps most of your readers by giving them fewer things to sift through. Consider not only the value of writing concisely but of reading quickly. Suppose you have a section on doodads. The section is much like the other sections that you have on widgets and gizmos. It has an introductory topic followed by a series of topics about major facets of doodads and then a subsection of reference topics in which users can find quick facts about doodads. So far, so good. Even supposing most readers read the section from start to finish, which is unlikely, most readings of your topic will be much more focused than that. Even careful readers will scan and skip to find the detail that they need after a thorough reading. Concise writing is skippable to enable concise reading. Build skippability by using clear, consistent headings, by well-formatted text, by concision, and by keeping a tight focus.

Effects

If you follow the pole stars of correctness, clarity, completeness, and concision, not only are you more like to actually write text that is more correct, clear, correct, and concise, but you also gain other benefits along the way. Your documentation will become more easily navigable. Part of navigability is the ability of readers to skip the parts that don't pertain to them. Required information becomes so findable that it almost leaps out at the reader. Overall, the user finds the docs to be painlessly readable rather than a grueling chore.

Further Reading

I really cannot recommend better than the following tools to help you practice clear, concise English usage. Completeness and correctness generally require more specific subject matter and interpersonal involvement than a book or website can provide.

English and Tech Comms Usage

  • Chicago Manual of Style online, or buy a copy to settle all questions about grammar and usage.

  • The Elements of Style, because it's inexpensive, brief, and an excellent guide to how to write clean and simple prose.

  • The Complete Plain Words, a broader work than The Elements of Style and - I'm not joking - good for daily reading. It teaches more about a mentality than about memorizing rules.

  • To The Point: A Dictionary of Concise Writing. You look up a phrase and this nifty book provides a briefer alternative. I use it when I am sensing my inner poet taking control of my tech comms work. The more you use it, the less you need to.

  • Microsoft Manual of Style for all language more specific to software documentation as well as formatting usage.

Feedback on Your Writing

  • The Hemingway App gives feedback as margin notes to help your writing. Generally, it seems to score with an eye toward helping you write very clean, active prose more or less suitable for tech writing. It gives lots of generally good advice about writing good, clean prose.

  • Readable.io evaluates text giving you a variety of scores based on different academic scales that I don't understand. But what I do understand is the simple letter grade that it gives. It also gives you some statistical feedback, such as the percentage of your words that are adverbs.

Special Note

Notice that I do not end with a conclusion. The formula of "tell them what you're gonna tell 'em, tell 'em, and then tell 'em what you've told 'em," is nonsense in technical writing. It might be good advice in oraton. I don't know. But in technical writing, only "tell 'em." If readers remain unsure, they can reread or you can improve your writing. Repetition makes the rereading harder.

Comments: