Home (contents) → Miscellaneous → Technical Writing and Programming

Technical Writing and Programming

Disclaimer: The views expressed on this page are mine and do not necessarily accord with those of any of my employers, past or present.

---

These links skip down the page to the applicable sections:

• Introduction
• The need for standards
• The importance of proofreading
• Read-aloud: An automatic proofreading aid
• Jargon
• Who should be a technical author?
• Why technical authors are unpopular
• Emergency parachute manuals

Introduction

Language, like hands, evolved not so much as a tool, but as a weapon. We all want to be experts and, in the shopkeeper mentality, simplicity is the enemy of the expert. Notice how people love to use abbreviations and acronyms where neither are necessary and only obscure meaning.

Write in such a way as that you can be readily understood by both the young and the old, by men as well as women, even by children.

— Ho Chi Minh

Communist Uncle Ho and capitalist Neil Armstrong (a former US Navy pilot, anyway) who was first to land on the moon (together with Buzz Aldrin) agree in this instance. After the space shuttle Challenger blew up, killing its crew of seven…

Armstrong was appointed to the presidential commission that investigated the disaster. Robert Hotz, another commission member, told reporters it was Armstrong who had led a fight to couch the report’s findings in clear, easily understood, nontechnical language.

— Kathy Sawyer, Armstrong’s Code, Washington Post Magazine, July 11^th, 1999 (linked later on this page)

People cannot write for others unless they are determined to do so and become practised in that art. They can write only for themselves. Why then would they need to proofread it? Language did not evolve solely as a tool for communicating facts to others (to your close friends and relatives) much as hands evolved as tools for making things, but as a weapon for kicking verbal sand in others’ faces — those who are not your close friends and relatives. (Much as hands also evolved as weapons.) Notice that teenagers often converse in a garbled lingo analogous to a ‘scrambler’ phone line, not for any conscious reason, but automatically. In attempting to get people to communicate clearly — proofreading being a part of that — we are rebelling against a basic instinct in people to preserve privacy of language.

Therefore, when we try to convey useful information in writing, be it in program source code or prose, we are acting counter to human nature.

See Source code and prose.

The need for standards

“The great thing about standards is there are so many to choose from.”

So said one of my hang gliding friends in connection with his work at the UK Meteorological Office. (The intentional irony struck me later…)

Why reinvent the wheel? I recommend the Microsoft Manual of Style for Technical Publications as a starting point for your organisation’s technical communication standards. Its English usage advice seems to be drawn largely from the Chicago Manual of Style. It is arguably too Americanized for some British tastes. Also, some software-specific terminology it advocates is particular to Microsoft programs, but most of its guidelines are generally applicable. You can always raise exceptions to adapt it to your organisation’s needs where you need to.

One reason for adopting writing standards in an organisation is that there can be several valid ways of expressing something. Do you push a button (in a program interface) or do you click on it? Neither. You click it. A published standard goes a long way to resolving such arguments.

The importance of proofreading

Proofreading is considered by some to be of questionable value, especially when deadlines are closing in and competent people are in short supply. However, its added value is second only to that of initial analysis and design. (An ounce of prevention is worth a pound of cure.) A proof-read is a low cost means of spotting and fixing mistakes easily overlooked by the originator. After all, you read what you meant to write, while others read what you wrote! If the item undergoing proofreading is so poorly structured or phrased that the proof reader cannot understand it, it is better to withhold the updated or new software from paying customers and thereby minimise potential damage.

Release note of the year, 2018, was by the unnamed manufacturer of a gyroscopic flight instrument fitted to Virgin Galactic SpaceShipTwo, which reached outer space at the hands of veteran hang glider pilot Mark ‘Forger’ Stucky in December 2018. On an earlier flight test, the gyro malfunctioned:

And yet, he suddenly realized, he wasn’t supposed to be looking down at Earth. This was the plan for tourist flights, but for this test the craft was meant to stay upright, allowing him to see only the blackness of space. SpaceShipTwo had somehow rolled over without his noticing.

“Oh, shit,” Stucky said. “The gyros are messed up.” For unknown reasons, they indicated that the spaceship was right side up.

— quoted from Nicholas Schmidle in The New Yorker, August 20^th 2018

I do not have access to the wording, but the release note either omitted or did not adequately emphasise its importance. (Release notes generally are categorised by importance from those pertaining to critical updates to those that have only superficial effect on the user interface.)

As it turned out, there had been a glitch in the gyros’ software; the manufacturer had issued a patch, but hadn’t indicated that it fixed a major problem, so Virgin Galactic hadn’t installed it.

— quoted from Nicholas Schmidle in The New Yorker, August 20^th 2018

So in this case, the fault had already been identified and the remedy had been supplied to Virgin Galactic.

---

With each new plane comes a book, a thick book, the Pilot’s Handbook, his bible, and it is chock full of terse admonitions describing various sins of omission and commission. These are categorized as to their seriousness, and put in little boxes to make them more eye-catching.

— Michael Collins, Carrying the Fire, an Astronaut’s Journeys, 1974

See also a Proof reading story.

Read-aloud: An automatic proofreading aid

In May 2021 one of my old flying comrades mentioned a Read-aloud button in his web browser, which I did not have. (I had never heard of it.) It is a Chrome extension, but I have the impression it works in other browsers too. I don’t like adding things to my computer because it slows it down, but I read a good review of its value as a sort of proof reader (see under External links later on this page) so I installed it.

I also discovered a similar facility built in to Microsoft Word. It is not an add-on. It has been sitting there for years waiting for me to use it. And it is so useful!

But what a faff! Having turned it on, where is it? In both Chrome and Word I had to click in an invisible divider between this or that toolbars (it all looks like one to me) and select something (I forget what) then ‘pin’ it to the toolbar…

I found that the synthetic speech in Word sounds more natural to me than the one in Chrome, but both are perfectly good. Well worth the pain of installing it in the web browser and making it available in Word.

Jargon

Write simply. Instead of “The biota exhibited a 100 percent mortality response”, write “All the fish died”, if that is what you mean.

Men love jargon because it makes them feel like pilots. Women love jargon because it makes them feel equal to men. However, it is easy to use jargon without realizing it. We pick up jargon much as we pick up language in the first place. It takes practice to notice that you are using jargon that a significant portion of your readers (or listeners) might not be familiar with.

I have discovered, however, that although my students nod knowingly when I deploy such terms in my classes, their comprehension is uneven, and they sometimes confound me by arriving at weird misunderstandings of what I was trying to convey to them.

— Daniel C. Dennett in chapter IV of Intuition Pumps and Other Tools for Thinking, 2013

The problem can be severe where an author has spent all of his or her working life in one arena, in which normal words are misused for quickness. To take a random example, one of many I encountered in the automotive sector, a wheel (to which a tyre is attached) is referred to as a rim. In normal life, a wheel rim is just the rim of the wheel, but to someone who learned a great deal of his or her language in an auto garage workshop, a rim is the whole wheel. That’s fine as long as you are certain that your readers have all undergone the same language learning experience as you have. You need to balance that against such oddities causing problems for translators and those whose first language is not English (or whatever language you write in). Furthermore, in my experience at least, such bending of definitions are more often than not confined to one geographic area or one organisation.

Who should be a technical author?

If you do not know why people around you chuckle when they see the heading Useful Links, maybe you are unsuited to be a producer of written communication.*

Similarly, if the difference between marketing spiel, release notes, and end user program help is not obvious, you need to seriously consider how you are going to add value by writing. Imagine the reaction of a frustrated user of a complex program who clicks Help only to read that the program he or she is using is easy to use. That’s an angry phone call to your help desk, for sure. Imagine further his or her reaction when, having controlled their initial rage, the ‘help’ goes on to enumerate the differences between the version of the software in question and a previous version, which he (or she) has likely never seen or heard of.

* I do not like to leave unresolved mysteries. The heading Useful Links implies the existence of an equivalent heading of related hyperlinks titled Useless Links. Always be alert to redundant expressions. (I nearly wrote unnecessarily redundant expressions.)

…the test pilot was supposed to put his plane into every conceivable kind of jeopardy, bring it out safely, and record precisely what happened before, during and after the crisis. It was in this written reporting that many test pilots failed…

— James A. Michener, Space, 1982

See my Pet peeves in technical writing.

Why technical authors are unpopular

Nobody likes being told what to write or how to speak. It is a bit like being told that you look weird or you ‘walk funny’. Therefore, technical authors need to be diplomats. Having said that, there is a limit to what a technical author or proofreader can accomplish in the face of adversity. (Garbage in, garbage out.)

Simplicity is the enemy of the expert

Despite westerners’ overwhelming subscription to free trade and market economics for the past third of a century, where each individual is supposed to strive for more efficiency, automating time-consuming and mundane tasks and freeing up resource to tackle higher level problems, they actually only want other people’s sons (and daughters) to be subject to the cold winds of the free market. For themselves, they want an automatic pay rise just for coming into the office and doing the same thing every day. Who are these technical authors who want them to give away their hard-won knowledge for free?

Further, when writing online help that reduces the enormous cost of staffing a call centre, you are taking away many people’s sense of worth: They like nothing more than being the expert that customers come to for advice. (The same advice, over and again, which is never forwarded to the technical authors to incorporate into the online help.)

Corporate culture

Corporate culture plays its part too. I refer to common corporate culture, not minor differences between companies.

Technical authors are educated, but almost always are not experts in the field. (That makes them better representatives of the kind of system users who resort to online help and managers who refer to release notes, incidentally.) In contrast, subject experts in some workplaces are often not educated (in the broad sense) and react negatively to technical authors engaged in activities with which more usual office workers are unfamiliar. For example, a colleague and I tested a convoluted process (for generating documents for paying customers) that I had written and was practiced in using. Because it was considered ‘business critical’, we needed to ensure that another technical author could use it in my absence. I sat behind my colleague, pen and paper in hand, while she went through the process, which took more than a full day, including sending questions to originators of text and diagrams, incorporating any corrections, sending them our preliminary documents for checking, and incorporating any further corrections. I intervened only when asked or when she went so far astray that the mistake would be unrecoverable. Those were the places where either my document needed clarifying or the process needed to be improved.

Anyway, some subject experts, having never seen such a co-operative test, clearly objected to this outlandish behaviour, especially after discovering that it did not originate from management. Something about sitting and doing nothing while watching someone else at work is an affront to their view of things. They consider their work to be their own private affair, with limited access to it granted, grudgingly, only to their own manager. This is generally applicable in private industry in Britain, incidentally, even in the defence and aerospace sectors. Presumably they feared this trend set by technical authors being adopted in their own areas of work. (Actually, I find it difficult to imagine why so many people are so concerned about how tech authors operate.)

One problem is that most managers find it necessary to ‘fit in’ with the existing corporate culture. It needs actual leadership to change corporate culture. Most of those with leadership ability are either unemployed or self-employed contractors and, thus, outside the ‘walls’ of corporate culture. Advocates of the free market immediately object to this statement. They argue that, eventually, companies that suffer the inefficiency caused by such negative cultures will be put out of business by more efficient companies. They said exactly the same about racism and sexism in the workplace: That companies who effectively employed people in accord with their abilities would put those with reactionary cultures out of business, so there was no need for government regulation to counter sexism and racism. A grand case of putting theory ahead of a century of evidence to the contrary. (Some went further: Saying that it proved that women and people with dark skins are less capable than the pale, male, and stale.)

Managers want to secure their own positions in the company and those of their relatives and close friends. They have little or no interest in improving ‘shareholder value’ or creating better products and services (Why should they? They want other people’s sons to be subject to the cold winds of the free market, but they want their automatic pay-rise for doing what they deem to be an outstanding job.) They perceive that security, at least in part, in terms of popularity among their colleagues and underlings — the very people from whom the destructive corporate culture originates.

The solution, it seems to me, is to copy the most successful technical endeavour ever accomplished. The moon landing program of the late 1960s and early ’70s was run by a government agency (NASA) which dictated to aerospace manufacturers who would make what, and how they would make it. There was much joking about space craft components being made by the lowest bidder, but that is not how it was done. (If it was, your local metal basher might have won the contract to build the Saturn V moon rocket.) That secured the careers of able and qualified people while cutting out the proverbial fat men in suits, who for the most part found themselves unable to cheat and lie their way into critical positions in the industry.

Emergency parachute manuals

In 2015 I upgraded to a newer emergency parachute for my hang glider. (As an advocate of spending money on modern equipment — within reason — continuing to fly with one made in 1978 is arguably out of order!) However, its instructions, which are full colour Acrobat (PDF) documents rather than the printed booklet with black-and-white photos of my old one, illustrate why most hang glider and paraglider pilots attend labour intensive emergency parachute repack events organised by hang gliding/paragliding clubs.

Step 4 of the procedure of my new one states “Flake the canopy in the conventional manner.” There is no hyperlink or any other reference to this ‘flaking’ in a ‘conventional manner.’ Because I have been repacking emergency parachutes for most of my adult life, I can make a reasonable guess at what they mean. In contrast, most people would be stumped at that point.

It is such a simple job, although critical (see more under Emergency parachute in Hang gliding equipment) but poorly devised instructions create havoc.

It could be worse. (Actually, it is worse…) At one repack event where they had a ‘zip wire’ rigged so that people could practice fully deploying their chutes prior to repacking them, one paraglider pilot, having successfully grabbed the handle and pulled the chute (in its inner ‘deployment’ bag) out of its outer cover (part of the harness) arrived at the bottom still holding the chute in its inner deployment bag. Why didn’t he throw it? (You are supposed to throw it as hard as you can into the clearest space free of spinning wreckage that you can see.) He explained that he did not know you had to throw it. He thought it worked like a skydiving parachute, whereby pulling the rip chord deploys it!

It is so easy to assume that everyone knows what you know.

Somebody just asked me why it is necessary to repack an emergency parachute if it has not been actually used (deployed) in an accident. It is to air the fabric, to prevent creases bedding in, to replace the rubber band ‘line stows’ (rubber can rot quicker than hyperlinks on web sites) and to check the integrity of the fabric. All of that ensures that it is likely to deploy quickly if you ever need it to. In addition, the annual repack provides the opportunity to hang up in your harness and practice throwing the chute, which is useful even without a ride on a ‘zip wire’. (You have to get it out to repack it anyway.)

I thought everyone knew that.

Related

And I am in the bag flight in Paragliding, an example result of an early translation computer program stretched beyond its capability

Document maintainability

Help for this web site

Programming career in About the author part 2

Web sites, social media, and language

External links

Armstrong’s Code by Kathy Sawyer in The Washington Post magazine, July 11^th, 1999

Improve your business writing with text-to-speech proofreading

Use the Speak text-to-speech feature to read text aloud: Microsoft Word help page