Noel Rappin Writes Here

I recently gave a workshop about technical writing at Virtual RubyConf 2020. I enjoyed doing that tremendously, because, in case it’s not clear, I could yammer on forever about technical writing in much the same way as I normally yammer on about code, just to a smaller audience.

I didn’t get to some of my outline in the workshop, so I’m being a little indulgent and writing it up here. I hope it’s helpful. It’s a few odds-and ends about useful techniques in technical writing.

The goal in technical writing is specifically to clearly explain an abstract concept to the reader. There’s a lot of science writing that is similar, technical writing is often different in that you are trying to explain a process that the reader is going to want to replicate. In some ways, technical writing about, say, how to use Tailwind to get responsive CSS, has more in common with food writing about recipes than it does with a lot of science writing. (Hmm… I didn’t include that analogy in the workshop, but I like it. I wonder if I should read some good narrative recipe books to pick up ideas.)

Because the subject matter is often complex, you don’t also want to make the writing style complex enough to make the style something the reader needs to figure out. (Yes, I’m aware of The Poignant Guide To Ruby and I love it, but I think of it more as a piece of art about Ruby then a great way to learn Ruby.) In particular, you want to keep the reader looking forward and, where possible, not make the reader backtrack to understand the text. Even small hiccups can add friction and make the technical content harder to absorb.

Toward that end, one of the first critiques I got from a professional editor was to avoid this construction:

TailwindCSS has the flex selector. This allows you access to flexbox layouts.

The problem in those sentences is the use of “this allows” without a reference. My editor would have asked me to change the second sentence to something more like “this selector allows”, on the theory that the missing word in the second sentence can cause the reader to have to stop and back up to figure out what’s going on. Readers are often good at guessing context, so you’ll probably get away with it, but why make a guessing game if you can make your meaning clearer with just a single word?

The larger point is that this isn’t golf, you’re probably not writing to a word count, and an extra couple of words here and there to enable the reader to focus on the actual content is usually helpful.

Another important part of technical writing is being able to support readers who might come to the piece with different amounts of experience. This problem is particularly acute with a blog post, where the reader is likely to encounter it out of context, and you have no way to know in advance who all is likely to encounter your article.

At the article level, you can deal with how to support readers by thinking about your ideal reader and what they know or don’t know. But right now I’m focusing on things you can do at the sentence by sentence level.

One of the first ways to improve the way your post supports multiple kinds of readers is to not use words like “obvious”, “easy”, “straightforward”. (I almost started the previous sentence, “one of the easiest ways to improve…", which I think goes to show that removing condescending vocabulary harder than you might think). There are a couple of reasons why it’s a good idea to remove language that is a marker for supposed ease. This language emphasizes the distance between the writer, who thinks something is “obvious”, and the reader, who doesn’t know the thing yet. Also, if the reader doesn’t find the thing obvious for whatever reason, then the reader suddenly feels bad and may even feel taunted. Upsetting the reader is not a good idea.

I find that vocabulary like “obvious” creeps in mostly in two places. One is if I want to compare an earlier step with a later, more complicated step. In that case, I still try to keep the condescending vocabulary out of it while still trying to give a sense of the increasing complexity.

The one that took me longer to figure out was that I found, somewhat to my embarrassment, that I was using this kind of language as a signal from myself to other expert readers that I, as a fellow expert, also found this step obvious. It was a measure of my own insecurity. To put it mildly, that kind of attitude is not helpful in technical writing, and understanding why I was doing it was really helpful in improving my language.

Another sentence-level practice that helps support multiple levels of reader is how you introduce and define terms that may be familiar to some of your readers but not others. I think the way to understand this is that the readers who are familiar with the term are perfectly capable of gliding over a definition they already know without being bothered. I My experience suggests that as long as you don’t over-signal that some information is only for the newbies, you can go a long way without people feeling that you are over-explaining. To me, this means the thing to do is present a definition without making a big deal out of it. If you do it right, the expert reader is just being gently reminded of something at the same time the novice is learning it:

So I might try:

Tailwind uses numerical sizes, each increment of 1 increases the size by 0.25 rem, where a “rem” is a unit equal to the size of the base font.

There are a couple of other ways I might structure that, what I want to avoid is something like this version, where the unit is unexplained.

Tailwind uses numerical sizes, where each increment of 1 increases the size by 0.25rem.

Or this version, where the explanation calls attention to itself.

Tailwind uses numerical sizes, where each increment of 1 increases the size by 0.25rem. In case you don’t know, a “rem” is the size of the base font.

I realize the last one sounds over the top, but I’m sure I’ve written worse.

Which reminds me, it’s very hard to put negative examples of “what not to do” in technical writing, and make sure that it’s impossible for someone to pull that example out of context and think it’s the thing to do.

One last sentence issue to discuss: what person to address the reader in? Whether to say “to solve this problem, I did X”, “to solve this problem, you need to do X”, or “to solve this problem, we need to do X”. I’ve gone back and forth on this issue so many times I can’t remember what my original position was. Many years ago, a copy editor changed all of my sentences to make the person different, and I remember being indignant, but I can’t remember whether it was switched from “you” to “we” or vice-versa.

My current guidelines are:

• Only use “I” to discuss something I actually did in the wild, not as part of a teaching example. I’d use “I” to discuss an interesting debugging problem, for example.
• In general, prefer “you will do X” to “we will do X” on the grounds that the reader needs to do the example on their own.
• But sometimes use “we” to draw the reader in, especially at the beginning of a topic, where I want the reader to feel like they have a partner.

That said, you can probably fine many, many examples in my own writing where I don’t follow these guidelines.

Hope that was helpful. I’m learning that nothing makes me self-conscious about my writing than writing about my writing.

Next time, we’ll take a little tour down memory lane and talk about the last 20 years or so of web programming.