First, a disclaimer: Medium served me this article, but it’s a year old. Weird. Nonetheless, I have things to say about the content.
The Virtues of Technical Writing, by a pseudonymous writer
Introduction
They are gleaned from a Bachelor of Science degree in Scientific and Technical Communication from the University of Minnesota’s Writing Studies Department, years of on-the-job experience, and lifelong self-guided study of the art and science of literacy. I share them here hoping only to bring further communicative light to the world. Heed them and prosper in all of your professional writing endeavors.
Coupled with the woodcut used to illustrate this article, this is exactly the kind of authority-derived advice that makes me gnashy. It’s all about sactioned knowledge and not the dirty fingernails of actually mucking with problems. I believe this person does do the mucking, but they’re not sharing that experience here.
In my experience (but lack of tech writing degree), software technical writing is a lot more like the pratfalls and triumphs of parenthood than any kind of art and science. Every child is generally similar in that they need food, love, and structure. Every child is vastly unique in how, why, and when they need those things. Software products are the same way.
Consistency
I’m not going to argue with this one. Consistency absolutely does matter, because anything else requires extra cognitive work from the reader. It’s our job to make their lives as frictionless as possible.
Thoroughness
always include a near over-abundance of information. Repetition and informational reconnoitering may feel redundant, but the confidence your readers gain from full insight into every step of the process will more than make up for the longer document.
No.
Let me repeat that.
No.
The more you make people read to get to what they need, the more likely they are to drop out. This approach addresses the needs of the long end of the tail over the vast majority of software users who are just trying to get this thing done so they can move on with their day. You need your documentation to be as short as possible while still covering the majority of scenarios. If you get questions or Stack Overflow notifications on some point you haven’t covered, then there is an audience for it, but otherwise, it’s probably just data for the sake of data.
Clarity
I’m also not going to argue this in the abstract, but I’m a little dubious about the absolute nature of assuming that removing words adds clarity. I’m currently editing a piece where the technical writers not only removed adjectives and adverbs, but also a bunch of definite articles. This is not actually useful, as it makes sentences a puzzle and not a seamless transfer of information.
My fourth grade teacher told me that the nouns and verbs are the muscles and bones of a sentence, and the adverbs and adjectives are fat. That’s a good way to think about it. Sometimes, a sentence needs a little plushness, a little padding, something to break up all the angular strength of what you’re saying. If each sentence is a perfect exact crystal, it’s like eating nothing but boneless skinless chicken breasts.
On the bright side, this is the first time that the user’s needs have appeared! So that’s a plus.
Hierarchical structure
The methods, style, and order of your hierarchical structure must first be universalized and then obeyed in every document if the implications of their design are to be understood by readers.
If your hierarchical style is not self-explanatory from the bottom level, you’re doing it wrong. Also, as I’ve been saying since 2012, very few people come to documents as documents. Instead, we encounter them as search results, and not all of the headings in the world are going to save your user if they can’t get what they need from the result returned to them.
We are not writing documents anymore, we are writing topics that are strung together. This is what Corilla is based on, this is what Madcap Flare and RoboHelp and every other modern writing tool that I can think of is based on. That’s because the basic unit of software documentation is no longer the document, or the man page, or the readme, it’s the answer. If your heading does not tell someone what question you are answering in the topic, be prepared to watch your bounce rate exceed your stick rate.
Introductory paragraphs
Agreed. Let’s not just plop some steps down without context. But you know what else you need? Next Steps. Now that you’ve done this thing, what are your increased options, your next configuration task, your results? If someone doesn’t know what they’ve done, can you really say they’ve done it?
Images and screenshots
Uuuuugh. No. Well, not a universal no. I agree that conceptual drawings can and should be used for multi-step processes. These images should be editable and have text labels that overlay the image if possible.
Here’s why we should NOT put images and screenshots in technical documentation.
- They are hideous to localize. You are adding thousands of dollars to a project when you do that, depending on your localization preparation and thoroughness.
- They are inaccessible. More people than you think are using screen readers, or their monitors cranked way up so the fonts are the size of fingerprints. Every time you say, “use the configuration settings from this screenshot”, a tiny exclusion demon gets its trident and stabs someone with low vision. Don’t do it.
- They change. It’s not that I haven’t tried to keep up with my developers, it’s that those charming individuals will move entire interface sections without telling anyone. The thing that is worse than not having a picture is having a WRONG picture.
- It’s 2016. We don’t need to show pictures of the screen because the odds are the user is looking at the help and the product on the same screen. Adding an image just gives you a recursive nightmare of non-flowing images next to the thing they’re describing.
Spelling, grammar, and punctuation
Fair enough, as long as you don’t fetishize them. Meaning is more important than form, every time. Sometimes I use sentence fragments for effect. Is that incorrect grammar? Sure. Is it effective at communicating my meaning? Absolutely, to English speakers.
If you find yourself convoluting to try to figure out how to comply with a grammar rule, the solution may not be to rewrite the sentence again, but just to tie a knot and go on.
I do care about punctuation consistency, especially around bulleted lists, but mostly that’s about the voice of the documentation, not The Rules.
Review and revision
I started writing this rebuttal at about 3. I expect I’ll publish it before 5. I expect I’ll iterate it.
Much like my developers, presenting a flawless product will get in the way of me presenting any kind of product at all. I have a system for tracking bugs in my documentation, and I fix and release. That’s all I can do. My review is essentially the same as an intergration test — does it compile, does everything in the package make it in, do I have any breaking errors? Beyond that, I would rather you had something now.
What’s missing
Where’s the user? Where in this whole system of virtues is the person we are supposed to be technically communicating with? When the user appears, they are an empty vessel, to be filled with information (Thoroughness, Introductory paragraphs, Images and screenshots) or running a race for understanding (Clarity).
As a technical communicator, my primary goal is to help people get things done. If we can design software better so they don’t have to read docs, I have succeeded. If we can make docs shorter or more nimble so they can do their work, I have succeded.
My value is not in writing. That is merely a manifestation of my real value, which is empathic, meaningful connections that allow people to get on with their lives, while incidentally using our software. My value is as much reflecting users back at the developers as it is reflecting the software into the user’s context.
I appreciate that this person wrote up their thoughts, and as you can see, I agree with many of their points, but overall, I think an emphasis on technique over understanding is an easy, tragic mistake.
I could speak with the tongues of humans and angels, but if I have not love, I am but a noisy gong.
1 Corinthians 13:1