Overview

Title: Developing Quality Technical Information: A Handbook for Writers and Editors

Authors: Michelle Carey, Moira Lanyi, Deirdre Longo, Eric Radzinski, Shannon Rouiller, Elizabeth Wilde

How I learned about it: Recently I subscribed to the technical writing subreddit, and I found this recommendation in a thread there.

Would I recommend: Yes, absolutely! In fact, I’m now convinced that every developer should read at least one technical writing book. This is the first such book that I’ve read, and so I’m not going to state unequivocally that it’s the definitive text on the subject or anything like that; however, it has been so wildly helpful that I can’t imagine not reading something similar. I bought a couple books from the thread I mentioned above, and I plan to read at least one other, if not multiple others, so hopefully in the future I’ll make a post comparing as many as I read and suggesting one (or multiple) that I like the best. That said, this book is fantastic, and I highly encourage you to read it!

General comments

First of all, why does a developer even need to read a technical writing book? Any of the following count as technical writing:

• In-house documentation
• Source code comments, docstrings, commit messages, etc
• Any communication about coding with teammates through Slack/Element/Discord/etc
• Asynchronous help on internet forums (Stack Overflow, Reddit, etc), whether you are giving or receiving it
• A personal blog or social media posts in which you talk about your work (hi!)
• Documentation for open-source / hobby projects

Even if someone else does the “user-facing documentation” for work, you’re writing a lot of words about technical topics, and every human on the planet - including future-you - is a user. It’s always worth taking some time to improve your writing!

The core of the book is divided into three sections, each consisting of three chapters. Each chapter covers a “quality characteristic” that good technical writing should have. I’ll go over each one later on. At the end of the book, there’s a two-chapter-long summary section that reviews all of these characteristics and discusses how to approach applying and revising content keeping them in mind together.

As you read the book, you can actively notice and appreciate the authors using their own advice, for example:

• They suggest to use consistent examples throughout an entire text, and they keep returning to an example of InfoDBase when it’s appropriate to use.
• They suggest to back up every point you make with “concreteness elements” like examples or analogies, and their own text is littered with the phrase “for example” (as well as examples).
• They tell you to address the reader directly, which they do consistently.
• They advocate having links between related topics; while this is impossible in a hard-copy text, they continually tell you about related points with page numbers, which is the next-best thing.
• They explain the importance of using entry points and navigational elements like tables of contents, which they helpfully provide at the beginning of every section, chapter, sub-section, and sometimes even sub-sub-section.
• Of course it is expected in a textbook, but they follow their consistent-visual-style guidelines for tables and other graphical elements.

One thing that stood out was their chapter table of contents on page 485 - they violate their own guideline of omitting repeating words in topic outlines; however, because they want section titles to be self-contained I can see why they did it. But I definitely saw it as an unclear, difficult-to-read outline in stark contrast to the other 99.9% of the book.

Definitions

They have a full glossary in an appendix starting on page 555; here are just a couple of the most important terms that I wasn’t already familiar with.

• Embedded assistance - technical documentation that’s written within a user interface.
• Non-contextual help - technical documentation that’s separate from a user interface (but will be linked to somehow).
• Progressive disclosure - the practice of guiding a user gradually from embedded assistance step by step to less direct documentation, including hover help, messages, and eventually non-contextual help, at each step revealing more details.
• Entry point - a visual element such as a section heading, table column heading, or link that indicates to the user where information is; a way to fight off “walls of text.”

Quality characteristics of technical writing

Here are the quality characteristics, divided into the three sections:

• It should be Easy to use:
  • Task orientation - A focus on tasks that users perform in order to complete goals, or real-life scenarios (think user stories!), and specifically NOT a focus on what the product is capable of.
  • Accuracy - Use techniques such as single source of truth, avoiding hard-coding values, and making notes in source code of where documentation refers to values. Talk to technical experts (ownership of code) & domain experts (ownership of product) to research, assign ownership to parts of docs, and have checklists completed & signed off on. Avoid showing specific timestamps, patch numbers, version numbers, etc, because that dates your docs. (This book actually violates this later on by showing a screenshot specifically mentioning Firefox version 10 on page 268 thus SUPER dating itself, I thought that was funny).
  • Completeness - Including everything that should be there, and, equally importantly, nothing that should NOT be there. Details are revealed through a pattern of progressive disclosure. Consider your audience and their skill level.
• It should be Easy to understand:
  • Clarity - Lots of grammatical lessons here, including a TON of suggestions about making content easy for translators. More on this below.
  • Concreteness - Write “for example” after basically every paragraph. As I mentioned earlier, you’ll notice that they follow this practice throughout this book, and it helps a lot. There are two types of scenarios: task scenarios (for users) and business scenarios (for prospective customers).
  • Style - Maintain consistency for everything you write. Make a robust style guide, and stick to it. Depending on your audience and medium, what’s appropriate may vary, but you always need something consistent.
• It should be Easy to find (things that the user is looking for):
  • Organization - Everything should be where users expect it. Contextual help is embedded assistance. There are three types of noncontextual help: conceptual, task, and reference. You should provide really solid navigation for your noncontextual help, including previous & next within each article; and an overview of all articles that actually explains the reading order and gives more than simply a list of all articles. Order task topics chronologically! And don’t accidentally overstate unimportant information.
  • Retrievability - You need to optimize both for searching and for browsing, which are opposite goals. Don’t over-link - technical documentation is not Wikipedia! Use entry points like table headers, section headers, dividers, etc, to fight off walls of text.
  • Visual effectiveness - People tend to be visual learners, and including illustrations, screen captures, charts, videos, etc, along with words is very valuable, but keep in mind accessibility! Don’t leave illustrations until the end or they won’t get done (or at least there won’t be time to iterate on them). Screen captures can help when UIs are complex (or bad), or when your users are very new and/or scared, but they are hard to update & translate, and they aren’t accessible. Keep illustrations, tables, etc, consistently styled! Similar to your writing, your visual elements should have a style guide with common elements etc.

Some specific translation suggestions

I think their advice about writing for translators and especially non-native English speakers is among the most important in the entire book, and a lot of it is also advice I never had considered before, so I’m summarizing some of it here. This summary isn’t exhaustive: (a) I’m not writing up a substitute for someone buying/reading the book, and (b) an exhaustive list would just take up too much space.

From the “Clarity” chapter

• Don’t start sentences with gerunds. This is discussed on page 156.
• Relative clauses are better than participles: “…the computers that are protected by a firewall” is better than “…the computers protected by a firewall.” Even though you might be tempted to leave out the words in order to make a more compact sentence that fits better in a cramped UI, you shouldn’t. This is discussed on page 159.
• “Phrasal verbs” like “shut down” or “line up” can be split like infinitives. These verb phrases are already confusing for non-native speakers of English, and when they are split like infinitives, they become translation and clarity problems. (Page 173)

There are a few more beyond this, as well as a ton of additional clarity tips written in this chapter that go beyond standard English grammar rules - but standard English grammar rules are covered as well!

From the “Applying more than one quality characteristic” chapter

See page 494. Again, I’m only mentioning some of their points.

• Avoid a marketing tone, especially idiomatic language.
• Avoid negative expressions (Bad: “not incorrect”; good: “correct”) - this is a big deal when naming variables when coding, too.
• Retrievability: make sure you use proper entry points like headings, etc.
• Completeness: provide only necessary detail.
• Make sure you use yyyy-mm-dd date format (or other non-ambiguous format such as writing out the full name of the month), and consider whether metric units are more appropriate than miles/inches/etc. (My additional comment: What’s the first day of the week? Don’t consider that implicit either. Also, you are making wrong assumptions about names.)

A couple things they get wrong

Most of these are just because the book is several years old at this point. And some of these have an implicit (in my opinion) attached to them.

• In the “Style” chapter, on page 274, they give some advice for avoiding subject-pronoun agreement issues when using gender-neutral language. It’s $currentYear, we can say “The programmer tracks their changes.”
• They talk a lot about hover tooltips. Like…a LOT. CONSTANTLY. But in today’s mobile-first world, hover tooltips are generally like a bonus-extra thing you add in for PC users, and you definitely want a clickable pseudoelement or something. They do mention that hover doesn’t work on mobile once or twice, but it still felt jarring to see hover talked about this much.
• In the “Clarity” chapter, I felt there were some missing explanations of why certain examples were incorrect; however, in fairness this isn’t an English textbook, and I guess if you find yourself questioning why many of the examples of incorrect sentences are in fact incorrect, then it’s maybe worth finding some dedicated English grammar book to read (I don’t personally have any recommendations).
• In the “Visual effectiveness” chapter, on page 430, they advise not to use night-mode text (they call it “reverse fonts”), but I think recent trends have been to give the user the choice to use standard or night mode viewing as much as possible, and the guideline should instead be to provide the user with this choice, especially when designing graphics (use transparent background and colors that can be inverted with CSS).
• There was also advice in the same chapter to use image maps; however, I would discourage the use of image maps if at all possible, instead preferring to use CSS grid and/or flex to build out a page that’s comprised of individual components that are individually linked and styled. Image maps can be used, but I definitely wouldn’t go out of my way to encourage them as a first choice.
• Not wrong per se but after reading Letting Go of the Words, I REALLY missed Ginny Redish’s angry faces, neutral faces, and happy faces as examples were progressively corrected lol - so much so that I sometimes drew them myself in the margins! >:( pls add these in the fourth edition :)

Conclusion

Every developer needs to write technical information, and Developing Quality Technical Information: A Handbook for Writers and Editors is a fantastic book that has already influenced my documentation. I highly recommend reading it! If you don’t want to read the entire thing, then I would suggest just these chapters:

• Task orientation
• Clarity
• Completeness
• Organization
• Retrievability
• Applying more than one quality characteristic

If you finish those and want to read more, then just skim around and pick out what seems interesting to you.

Happy writing!