Technical writing and programming


Home (main menu) > Articles > Technical writing and programming

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

Photo of a man placing a pen against a computer monitor

Technical writer

 

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.

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 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.

 

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.)

See my pet peeves in technical writing.

 

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 it from paying customers and thereby minimise potential damage.

See a proof reading story.

 

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.)

 


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 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.

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.

Internal links

Bondsmanship, a programming and technical writing digression from Saving Major Tom, my review of the 1967 James Bond movie You Only Live Twice

Dangers of hang gliding

Hang gliding equipment

Help for this web site

Advertisements

One Response to Technical writing and programming

  1. Jon Howes says:

    Hi Everard,

    Regarding your comments on unecessary words, Neil Kinnock, former Labour Party leader, was a master of this. My favourite was “bogus sham” during a particularly memorable speech about the time of the first Iraq war.
    Jon

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s