TECHNICAL WRITING: COMPLAINING AND EXPLAINING

“Never complain. Never explain.” is the unofficial motto of the British royal family. It expresses the stiff upper lip attitude which is stereotypical of the people of modern England. I am not sure how much of that we Americans inherited. The continent was settled (invaded) by malcontents who formalized the political structure of their society with a revolution, opening the land to others of their kind. So, we tend to complain a lot and explain even more, whether anyone wants to listen or not. 

Two years ago, my colleague, CJ, posted a comment in response to “The Origins of Technical Writing.”  I tend not to reply to comments, but I am working my way through the same sort of resistance on my present assignment.  CJ wrote: 

“I have a somewhat negative view of tech writing because they seem to just restate things verbosely. Sometimes there's a a button labelled Var Osc Mode. I look in the manual, and they've padded it: "The Var Osc Mode control toggles variable oscillator mode. " It's unlikely anyone who understands exactly what that means would not have understood by reading the button.” -- CJ December 18, 2017 at 7:08 AM

First, you never know who will be using your work and reading your explanations. That is why Scientific American follows the same inverted pyramid structure as The New York Times. The “5Ws and an H” provide an easy framework for the opening paragraph. From there, you have to explain from broad, general truths, down to the supportive details. When I write, whether it is about machinery, software, state government agency policies, numismatics, or astronomy, I want the reader to care about the consequences of this new information. 

 Second, you do not know how your invention will be applied, or how the reader intends to adapt the information. One of the consequences of technical progress is that scientific theories, new discoveries, and innovations find novel practices. Time-traveling back to 1920, how would you explain to an astronomer from Harvard that today's markets provide computer controlled telescopes to hobbyists for less than the relative cost of a trip in that time across the Atlantic by ship? The hobbyist astronomer today is not necessarily a computer programmer. 

Similarly, the clever search algorithm committed to Github could be used by a lawyer for a music publisher needing to search for studio performers who are owed royalty payments. The 21st century lawyer may well have learned programming in some earlier education, but without good internal documentation your routines will not become her methods.

Third, you do not know how your reader came to your language. English is the universal second language of Earth. I believe that by the middle of the century, Indian English will surpass the American vernacular in global popularity and therefore, ultimately, in technical writing. In the meantime, my focus is on North American English. I think about my readers who are immigrants from India, China, and Mexico. I write in the language they hear at work, on TV, and on the street. (See, Spoken American Grammar here.) However, my work is always grammatically correct because grammar provides the rules of language; and language determines how we think.

Fourth, you do not know the literacy level of your reader. English pushes the limits of vocabulary at almost one million words, having absorbed mulligatawny, moccasin, mullah, and mutton. I change the engineer’s “utilize” to everyone’s “use.” My worry is for the motivated but underpaid lone operator on a midnight shift. The engineer who knows how the Var Osc Mode functions is home asleep, enjoying the privileges of their false class consciousness as a white collar employee while someone else is on the front line and in the trench with a machine in a variably oscillating failure mode.

The reason that my user manual only defines var osc mode as “variable oscillating mode” and says nothing more is that the engineer does not consider it important enough to make time for me. I try to interview subject matter experts. They claim to be too busy. I recently had one engineer flat out refuse to put in writing what he just told me verbally, expecting me to have instantly memorized the pearls he was tossing. 

Recently, one of our field service engineers used MS Word Track Changes to make extensive notes in the margin. I thought that he could have just as easily put them into the body of the document in the first place. But the formatting failed when I cut-and-pasted them in. The previous engineer who designed the form must have invested many hours in tweaking MS-Word to get this to print out the way he wanted. It does look nice, printed on A4 paper. But it is unsupportable. The overbuilt formatting in the table cells is hard to use, hard to maintain, and hard to change. And in America, we use 8 ½ x 11 paper. That speaks to my role designing forms. 

The other side of that coin comes from the people who never got over the typewriter. They try to line up text using the spaces and tabs. I create a table and then turn the borders invisible. It looks nice; and it is easy to maintain. 

Moreover, our on-site technicians are as likely to use a tablet or a phone, rather than a desktop computer. I have been aware of that since 1990 when I published an article in Credit Union News about new platforms for computing. Hughes Aircraft was experimenting with a 1-inch screen worn on a headband. The little box projected a standard page. It would enable a technician to bring a service manual into a turbine engine without actually dragging a rack of manuals into the engine.

I came to technical writing by way of computer programming. I was on a database project at General Motors; and no one wanted to write the user manual. Having sold two small books and half a dozen magazine articles, I gave it a try. 

I never left programming completely. All computing is programming, even for Facebook. Through the 1980s, I tweaked the codes in WordPerfect and learned to set type with Donald Knuth’s TeX/LaTeX. TeX became SGML, the Standard Generalized Mark-up Language. SGML became HTML; and now we have XML, the eXtensible Markup Language, leading to YAML (yet another…). Most of the computer people I socialize with think that CSS is Cross-site scripting. But in my work, it is Cascading Style Sheets. We do not have them in MS-Word, but the concept is helpful when thinking about documentation across manuals and departments.

I can make MS-Word sit up and bark. And it’s a good thing that I can because the cliché that I hear when I try to explain how many extra hours, days, or months something will take is: “That’s OK. We have a budget for manpower, but we do not have any extra money for software.” 

What really do I get paid for is the Index. Back in 1966, when Capitalism: The Unknown Ideal, was released, I understood and appreciated the fact that the Index was written by a philosopher (Allan Gotthelf) following the epistemology of Objectivism. I have three copies of Introduction to Objectivist Epistemology. Over the decades of my productive working life, I have worn them out by reading them and marking them up. 

PREVIOUSLY ON NECESSARY FACTS

Documentation is Specification

For the Glory of Old Lincoln High 

Art and Copy

Linguistics Debate: What Colors are Your Rainbow