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
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.
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.
To start with what might seem a digression, people can only make a cup of tea for themselves. Here is how it goes:
Me: “Yes please. Only half a cup. Black, two sugars, no milk.”
Host: “OK. Half a cupful. Black, two sugars, no milk.”
Host (a minute later, handing me a huge mug filled to the brim with off-white hospital tea): “Half a cupful. Black, two sugars, no milk.”
Me: “You put milk in it.”
Host: “Oh! So I did! I must have mixed them up. I’ll make another”
Similarly, 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, which includes a snippet from my still unpublished novel.
“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.
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.)
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 20th 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.) In this case, the fault had already been identified and the remedy had been supplied to Virgin Galactic.
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 20th 2018
See also a proof reading story.
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.)
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. 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.)
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 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 many hang gliding/paragliding clubs.
The accompanying photo is reprinted courtesy of Ultralight Flying! magazine.
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, 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 when you 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.
Bondsmanship, a programming and technical writing digression from Saving Major Tom, my review of the 1967 James Bond movie You Only Live Twice
Forger in Space flight and hang gliding, about the adventures of hang glider pilot and astronaut Mark Stucky, call sign ‘Forger’