The Cardinal Virtues? of Technical Writing

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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

The Seven Righteous Fights: Overview

This is a series derived from my popular talk “The Seven Righteous Fights”. It’s not an exact transcript, but I think having a written form to refer people to greatly increases accessibility and gives me room to expand my thoughts in a way that is not compatible with speaking.

There are seven fights that I have over and over again, whenever I start at a company. The more software you build, the more it’s obvious that there are seven fights that it will alway pay to have.

My background as a writer means that I am trained to perform a lot of analysis and synthesis. If I don’t understand the product from value proposition through implementation, it means that I am not the writer I want to be. I call it being a full-stack writer. The problem with having all this training in analysis is that you can’t exactly turn it off. I don’t stay in my lane well, I can’t notice problem that only fall into the narrow category of “documentation”. They’re all documentation problems, they’re all software problems, they’re all design and usability problems.

I’ve worked for roughly 15 companies and my conclusion is that when we create something new, we tend to make similar mistakes every time. This is probably because we all tend to settle in a comfortable stage of product development. Some people prefer mature products, some people like the very beginning and hate the mature product maintenance. But that preference means we don’t understand pain points that happen at other stages.

I’m an early-stage person. I love writing the first version of documentation. I love that green field and that new product smell. But I have done enough mid-stage stuff to know the emergent consequences of early-stage decisions. And like everything you’ve ever read about compound interest, early mistakes compound until they are enormous.

I was working with a startup that was pushing super hard to get their product ready to demo at a big industry conference. They were stripping off every feature they didn’t absolutely need in order to make sure they made their deadline, and I was helping. We made the deadline, there was documentation, and they got a POC contract… with a company in Brazil.

In the process of rushing to get ready, we had stripped out all of the plans to make the interface labels link to a file we could localize, and we had hand-coded all the labels. Now instead of handing off a single file to be translated into Portuguese (and having standard labels that could have been done with Google Translate, in a pinch), we either had to branch and hand-code Portuguese labels or spend twice as long digging into the original code and fixing what we had hacked. I’d love to tell you we decided to do it right, but you all know too much about software to believe that happened, don’t you?

The compounded interest from not using a best practice of referred labels when we built the user interface cost us five days of developer time to fix the wrong way, and two weeks to fix and rebuild the right way. That’s a relatively common example of things people skip and pay for later.

Leaving important considerations “until we get a working prototype” means that it’s going to be harder and more expensive to retrofit. Having these fights early prevents you from doing the software equivalent of poking chocolate chips into already-baked cookies.

cookies

Next: The Seven Righteous Fights: Localization

If you’d prefer to watch the talk as I delivered it:
Shortest recorded version: At The Lead Developer 2016

Longest recorded version: At SpringOne Platform 2016

Contract additions

Last year, I signed 4 contracts for work-for-hire. I estimate that will be average-to-low going forward, but I don’t have enough data points.

Every time I work with a company, I come up with something I want to remember to specify for the next time, or at least attempt to negotiate for.

Summary:

Work-for-hire does not entitle anyone to my other intellectual property.

Pay me. On time.

Give me the tools to do my job.

Intellectual property grabs

Someone, somewhere, has built a really terrible work-for-hire contract that specifies that anything I create while I’m working for a client is the intellectual property of the client. That’s just laziness. Or at least, I hope it’s laziness, because otherwise it’s greed. If I didn’t watch out for that clause, I would sign away authorship of my tweets, my blog, my fanfiction, my work for other clients. Strictly interpreted, if I signed that contract and wrote the Great American Novel, $large-employer would own the rights to it. To any patents I obtained. To any of the fruits of my mind.

I’m not ok with that.

Almost always, I point out that the clause is over-broad, and what on earth are they thinking, and the hiring manager apologetically crosses it out and we carry on. But it makes me cranky every time.

I’m doing work for hire, which is a really specific category of labor that means I retain zero rights to the things I produce for pay. I can’t even use them as writing samples unless I get written permission. Played out in another industry, it means that the woman who provided all the phonemes for Siri’s voice a dozen years ago does not get paid by Apple. She did work for hire, the company that owned that resource sold it to Apple, she gets nothing. Which is hard luck for her, but is the way work for hire is. Most of the time, the things I write are wrong or obsolete in a handful of years anyway. The company is welcome to keep them.

Payment terms

I pay bill.com $15 a month or so to manage my invoicing for me. I enter in all my hours, they send email to my clients, and my clients click ONE BUTTON to transfer money from their account to the ACH system, which means I get a direct deposit. In the last year, this has worked correctly about half the time.

One employer insisted on cutting paper checks, 30 days after I invoiced them, and mailing the checks, which I then had to deposit. That did NOT make me feel favorably about working with them. Also they fired their accounts payable person and didn’t tell us. Ugh. This whole system made me feel like they were going out of their way to extract maximum interest from money I had earned.

One employer was surprised that I did not like the idea of billing monthly and then getting paid 30 days later. I know I should have a cushion and all, but YOU imagine not getting (probably) paid for two months after you start work. On a three month contract. Also, they were not clear that the ACH system only works on bank days, and does take some time, so if you start the payment on the 15th, I will not get the money until the 21st, and I will be cross.

Two employers were a delight, paid promptly and painlessly, and I have nothing to complain about.

My takeaway is that I am adding a late-fee clause to my next contract. If you don’t get me the money on the day we agreed, much like my car loan people, my rent people, my credit card people, and every other business on earth, I will charge you a late fee. I’m currently considering how much would be enough to motivate good behavior without seeming ridiculous, but late payments have cost me at least $500 in the last year.

Also, I always at least make a bid to get time-and-a-half if I go over 40 hours. I have to do crunch, but it’s worth at least asking if they’re going to pay me for my midnight oil. This rarely works, but perhaps it moves the Overton Window?

Hardware and access

When you’re an employee of the tech people type, you expect to get a computer when you walk in the door. That is your work computer, you use it to do work things, it connects to the corporate email and the Confluence and the VPN, it has an image that is supported by IT (assuming there is an IT). When you leave, you give it back to the employer, slightly deprecated, perhaps covered in stickers, and hopefully without any unfortunately embarrassing files.

When you are a contractor, it’s all a bit muddier. Half the jobs have provided me a computer to do my work with. Half of them want me to bring my own device. The problem with bringing my own device is that I may be far outside of the norm for what they expect. If my employer does not purchase it for me, I do not have a MacBook of any description. They’re fine pieces of machinery, but they do not run most technical authoring programs, and the thousand-dollar markup is a bit steep for me.

This was a real problem when I was contracting with a Mac shop. They would send me instructions on installing the software using homebrew, and I’d have to say, “I can’t test that, I don’t have a machine for it, could you please just set up an AWS instance for testing for me?”. Over and over, they’d forget that I was just not running the same OS as they were.

It’s a problem when the VPN the client is using and that I must access hasn’t been updated since 2012 and doesn’t support Windows 10 (what I’m on), Windows 8.1, 8.0, or 7. NOW how am I supposed to see the product?

Everytime I hit one of these roadblocks, I spend time that I could be spending on writing the documentation wrestling with the toolstack. I guess if you want to pay my consultant rate for me to watch youtube videos about hand-editing my registry, I’ll do it, but I’m pretty sure that it doesn’t take many hours of that to make it cheaper to just send me a computer set to employee specifications, or build me a dedicated hosted test instance. If only we had a globally-accessible cloud of computers which could be securely accessed and used to run software, eh?

When I finished in 3 or 6 months, I could send the computer back. You’d have access to all the source files AND the software that I used to write them, I wouldn’t have mucked up my personal computer with your weirdo firewall hacks, and everyone would be happier.

You know that tweet about how you have to get approval to spend $500, but you can call a two-hour meeting and no one blinks? That is so visible in contracting.

So I’m going to see if I can add a hardware provision into my next contract. I can’t write about your software if I can’t use it, and I can’t use it easily if I don’t have the same toolstack that your developers do. And I’m AWFULLY expensive as a mediocre IT administrator.


What about you? Do you have anything you write into your contracts?

I’m still debating about how I feel about insisting on a site visit. It usually makes my contracts go better, but it’s also awkward to arrange reimbursement if I’m not in the sytem, etc.

The three documents you ACTUALLY need first

Because I work as only-writer for so much of my time, I forget that I’m not just a lone technical writer, and I’m not just an indie, but I’m in an odd category beyond that. Because no one who hires me really knows what a technical writer does, interviewing is often turned on its head for me. I do a little research on a company and then walk in and explain to them what the first three documents they need me to write are. It makes me look like a genius, and it has a reasonably high success rate. Also, it stops them from explaining their business model to me. If I haven’t figured out your business model, and you aren’t in stealth mode, the first thing we need to fix is your web presence.

The three documents that people think they need first are: Installation guide, User guide, FAQ.

The three documents that people probably actually need first are: Developer onboarding, Configuration, and Sandbox.

Developer onboarding

By the time people get around to hiring me, they are exploding their hiring, and adding developers as fast as they can find them. You can either hand them a document on setting up their environment (or better yet, a pre-built VM), or you can devote your existing developer’s time to walk them through a process that has a dozen backtracks, and no one gets anything done for a week. I am SO MUCH CHEAPER than manual onboarding, and a document SCALES, unlike the one person who understands how to set up your development environment.

Configuration

Most of the software I’m working with now comes in both hosted and on-premise flavors. Ignore the on-premise for as long as possible, because it’s always a nightmare of idiosyncracy. Instead, drive people to use the hosted solution by offering them the MUCH SIMPLER configuration guide that lets them set things up the way they want without having to build an environment from scratch.

Sandbox

It’s no good telling people how to use something if they have no motivation to learn. The people that you need to talk to if you are in the early stage of going public (publicity, not IPO sense) are not the same people who will be compelled to learn the software because they need it day in and day out. The audience for new products is the decision-makers, who are often far removed from the daily grind and who have no motivation to learn step-by-step. No, they want to play with the product and see what it’s capable of.

If you give them a way to make the experience touchable, real to them, it’s going to mean more than a dozen slides and even hands-off demos would.