Technical Writing Notes

by

Stephen Lowe

lmsfarm@gmail.com

July 2009

CONTENTS

 

CORE SKILLS

"Did you know that if you leave alphabet soup on the stove while you go out, it could spell disaster?" —Anon.

It is my belief that for the majority of engineers (mechanical, structural, electrical, electronics, software, etc) the documentation is the boring bit. Managers seem to have a slightly different take on documents — they concede that the pen may be mightier than the sword. Engineer or manager, good documents take time; time they would rather be using in other ways.

Enter the technical writer. This person must be able to: grasp the importance of the work in hand; recognise the devil in the detail; quickly master the appropriate language and style; be trusted in complete confidence; and be relied upon to meet deadlines. It goes without saying that their English language skills must be excellent, and their ability to research and find facts second to none.

While documentation might be seen as the drier side of an industry, it is not totally devoid of interest and even, sometimes, humour.

Grasping the importance of the work in hand

Surrogate activity (fiddling while Rome burns), and burying one's head in the sand are common departmental phenomena. It may be that the real problem is known, but not admitted to. It may be that the real problem is known, but that the work is accelerated in the hope that it is fait accompli by the time the real problem is discovered by the people who hold the power of veto. It may be the engineers are so engrossed in their activities that they are genuinely unaware of the real problem, looming on the horizon like the dark clouds of an approaching storm.

Work-in-Progress
The engineers of the Sardar Sarovar Projects would have been preoccupied with calculations, models and projections. Perhaps they can be forgiven for failing to notice that no provision had been made for hundreds of thousands of affected people. Perhaps they should have looked at that clause of the Code of Ethics for Engineers that states: "Hold paramount the safety, health, and welfare of the public..." (or some such, depending on exactly which institution they belong to). Perhaps we should all look at our codes of ethics from time to time, because they represent the big plan. The dam builders thought the problems they had to solve were measured in cumecs. The real problems they had to solve were measured in lives and livelihoods.

In The Soul of a New Machine, in a chapter entitled The case of the missing NAND gate, Tracy Kidder expertly documents and characterises the debugging process. At one level the problem tackled by Veres and Guyer is one of finding a logic error in the prototype Eclipse computer. At another (higher) level the real problem is the passage of time. As the days and nights of intense intellectual effort continue, Holberger, on his morning drive to work, notices the season changing. This is an obstacle race to win market share, and the missing logic gate is just one hurdle along the way.

A technical writer can hide in a cupboard near repro, or she can ride the elevator to seek an audience with The Boss. Whether she chooses to play dumb, or to play devil's advocate, it is likely that in doing her job thoroughly she will become aware of the big picture.

Recognising the devil in the detail

When first I went to sea we used slide rules, not calculators. This gave us a big advantage over our successors who found it quite easy to make an error of three decimal places, giving them a noon position a thousand miles away in the middle of the Sahara desert. With a slide rule you need to have a common sense answer already in your head, then the slide rule fills in the detail.

Wrong units is a great way to cause huge errors with hilarious consequences. Try setting your tyre pressures to 2 lbs/sq.inch or 32 bar! I'm reminded of a passage in The Hitchhiker's Guide to the Galaxy: "due to a terrible miscalculation of scale the entire battle fleet was accidentally swallowed by a small dog" (Adams, p.129).

Mastering the appropriate language and style

There are times to be impersonal and formal, and there are times when this can be relaxed. Always it is vital to retain strict control over opinion and fact. Opinion really only has a place in technical reports when it is expert opinion, and when it is clearly flagged as such. Technical writers could be said to search for the right "voice" for a document, then they lock into that voice.

For example Bradford Morse and Thomas Berger in their covering letter to Lewis Preston wrote: "We think the Sardar Sarovar Projects as they stand are flawed..." and that's fine—Preston had asked for their opinion. In the report, however, they adopt a more formal tone: "Measures to anticipate and mitigate environmental impact were not properly considered in the design of the Projects..." and this can be translated to read, "We think they're flawed..." There's one other clue I'd like to point up here. When Morse and Berger write: "as they stand..." they leave the door open for negotiation and change.

Every document has its target audience. Correctly identifying the target audience drives the style. A car manual may address the car owner directly and personally: "Now you are the proud owner of..." By contrast, if one were to address operators-under-pressure in this way it could be intensely irritating: "Now you are the proud owner of an unconscious diver why not try injecting him with adrenalin?" Well, that's a ridiculous example, but I have made my point.

Proceeding in confidence

Technical writers emerge from various disciplines, I came from software engineering. That explains my membership of the New Zealand Computer Society. It would be fair to say that the NZCS had got stuck in the doldrums, but recently the good ship has caught a breeze, and is on track to becoming a serious professional association. In future, members of the society who wish to be fully-blown professional members will have to follow a programme of certification, and demonstrate so many hours of structured professional development each year. This is a Good Thing, and will, over time, lead information technology people to enjoy the same kind of status afforded to engineers and accountants. We have a Code of Ethics to which we are required and would wish to adhere. As technical writers make such heavy use of information technology (word processors, page layout programmes, charting packages, web publishing packages, document management systems, etcetera) it is worth considering joining the NZCS. Whatever you might have heard, it is now a go-ahead society on a worthwhile mission.

From time to time technical writers may be asked to sign a non-disclosure agreement (NDA). If the professional status mentioned above is in place it should go almost without saying that the technical writer will be aware and respectful of the confidential nature of the material they are handling. Nobody should mind being asked to sign an NDA, it's a token of their status that they should be entrusted with insider knowledge.

Meeting deadlines

6-minute incrementsPlanning the production of technical documents should be taken as seriously as planning the product itself. In the tools section of these notes I will cover Gantt Charts and the swim-lane activity diagrams of the Unified Modeling Language (UML). Here, suffice it to list some common mistakes that occur as a result of poor planning: the person who has the content for page 144 is away on holiday; the repro house does not accept files in your format (and when you try converting to another format the pagination breaks); two weeks out from deadline you get a weird flu bug. Planning, scheduling, identifying and managing the risks are as much a part of a technical writer's job as a project manager's. When a project manager asks you questions like these, it will look good if you already have some answers.

There is a fundamental truth, expect what you inspect. "Repeatedly point to the calendar, your project will be on time" (Scott cited in Cooper, p.85). Put another way by Bob Parsons of GoDaddy, "Measure everything of significance." For my part I print 8 decahedrons on an A4 page and mark them off as my day unfolds, creating a key to the side for various activities. Measuring my time in 6-minute increments like this I find that I can: bill accurately, identify wasted effort, ensure sufficient screen breaks.

Jump down to a spreadsheet which has been used to create a UML-style swim lanes activity diagram that served as a schedule for the production of a short commercial video. This is a great way to go, especially if you can create it together—then everyone on the starting blocks owns the race.

English language skills

I read an online news item that said some teenagers had been killed in their souped-up car. I thought, is it not suped-up? Is the origin of this (now somewhat quaint) phrase not the fitting of a supercharger to create more horsepower for racing? An example of how language changes as it moves from jargon into common usage is "plain sailing". Plain sailing is what every journalist writes these days, but it should be plane sailing. The expression has its origins in the technique used by navigators where on short voyages they assume the earth to be flat to simplify the calculations. This rather nerdy approach to language and obsessive attention to detail is the hallmark of good technical writers.

Researching and finding facts

You couldn't really sell your services as a technical writer if you hadn't done at least one course called something like "Research Methods". People who have degrees have done these kinds of papers by default. Also required is at least some knowledge of statistics, if only to know some of the language of statisticians, and to be able to spot BS on your BS Detector when you strike it. During the time I worked as a night sub on a provincial paper I honed a kind of sixth sense around made-up facts. It is not uncommon for hard-pressed writers to skirt hours of patient research and replace it with an educated guess. Who really can blame them? However, the technical documents of a corporation, institution or organisation are its public face. Further, these made-up facts have a way of surfacing years later and can cause great embarrassment. It is, therefore, important to schedule sufficient time to do the research and to check the facts.

 

TOOLS

"Actually if a writer needs a dictionary he should not write. He should have read the dictionary at least three times and then have loaned it to someone who needs it." —Ernest Hemingway

Old faithfuls

Actually I don't agree with Hemingway, I included the quotation because it's funny (nor do I like starting sentences with actually). My favourite dictionary is not a huge one, it is just 1300 pages, but it has 55,000 real examples, drawn from the Bank of English. These real examples are a really quick way to see how a word is correctly used. Also there is a good grammar at the front (with more grammar than most technical writers will ever need) referenced from the entries. For example: Imagine you are editing another writer's work and you come across "exegesis" (not a word one uses every day); the entry for exegesis shows it to be an N-VAR, a variable noun; there is then an explanation, and four generalised examples—very useful indeed. This favourite dictionary of mine is the Collins Cobuild Learner's Dictionary.

Quaint though it is, Fowler's Modern English Usage still gets lifted down from the shelf several times a year. "Leading question" was an entry I had need of just the other day. "Smoking gun" is not listed, but I wish it was. Or should I say, I wish it were?

The Style Book is an essential tool for any writer, and one that should never be far away. This is how one resolves those little blocks we all have from time to time. To pick one almost at random: "9.40 any more: always two words." The book is indexed, making it particularly useful as a quick reference.

I don't know about you, but I didn't pay attention in grammar lessons. Nitty-Gritty Grammar is "a not-so-serious guide to clear communication" which deals to the basics that we should all know. I have used it in Business Communications classes as a standard text.

Innovations

Google has revolutionised research and fact-finding, there can be no arguing that point. Few people, however, make even partial use of Google's advanced features, possibly because the standard features are so good. Advanced search strings like rock +and * can be learned from any tips and tricks site, as can unit conversions like 27mm in inches (1.06299213 inches), and population of New Zealand (4,173,460). Wolfram Alpha gives additional material that may be relevant to what you're trying to achieve, for example 15.6 people/km^2. Google Scholar, Google Booksearch, Sketchup, and Translate are just some of the free and innovative tools on offer. The fun really begins when you acquire your copy of Google Hacking for Penetration Testers Volume 2, suddenly you learn a whole lot of new ways to get information!

Anyone can get a free Google account. It's not only the full-featured email account though, that's just the start, it's the Google Docs that are hot. The calendar can be used as a project planner, then there's a word processor document, a form for surveys, a spreadsheet application, and presentations. All these documents can be assigned an owner, and then shared with or hidden from others. The data is stored on Google's servers, and accessed by you from anywhere online. It's called "computing in the cloud". It is especially suited to, say, getting some documentation going across a nationwide franchise where you need input from a couple of dozen different managers. There are some issues, but for certain projects they are outweighed by the flexibility and the zero cost.

Not living in a University town, and having space for only a couple of hundred books at home used to be a real constraint, but now I have a subscription to the digital library on IEEE I have instance access to a truly vast science and technology library. I would recommend any technical writer either get a subscription of their own, or persuade their employer to get one.

Sometimes innovations aren't big things reported in Wired News, sometimes they are simply neat ways of using existing tools. Alan Cooper in his book The Inmates are Running the Asylum describes "feature list bargaining" (Cooper, p.46). In this game programmers bargain with managers, and the stakes are features and time. I have often facilitated such games. The simple tool I deploy is a spreadsheet. In one column I write a description of the feature, in another a numeric rating of the value of the feature to the project, in another a rating of the complexity of implementing the feature, in another the estimated $ cost. Then we can sort the list of features how we want, and we have a tool that facilitates the bargaining. I imagine this is the way lots of teams proceed.

Software packages

I have found the following software packages very useful:

Bespoke tools

I have created a few hand tools of my own. Most are quick appraisal tools, amongst them:

Usability Test
30-minute Business Plan
1-minute project risk analysis
 McConnell Project Survival Test

I have found these tools very useful as I make a decision on whether to accept or decline a commission. The 1-minute project risk analysis can be done while talking on the telephone. The usability test can be done by a disparate group in an hour if access to the software being tested is online. It is rewarding to make your own tools, simple software that does exactly what you want and no more. The Project Survival Test is based on ideas by Steve McConnell.

Project management tools

Many of the (usually open source) project management tools must be pitched at corporate America, they seem to be sledgehammers for cracking nuts here in New Zealand. What is the point of a productivity package that takes a year to learn?

I have four solutions:

I have yet to be involved in a project so big that these singly or combined are not sufficient. "Sticky notes arranged on a cork board" needs some expansion. There is an excellent book by David Straker titled Rapid Problem Solving with Post-it® Notes. Straker introduces six problem solving tools: Post-up; Swap Sort; Top-down Tree; Bottom-up Tree; Information Map; and Action Map. This book saves you a year at management school.

spreadsheet as swim lane activity diagram
Figure: Swim lane activity diagram used for a schedule.

Features of the above swim lane acitivity diagram include colour coding for quick reference (imagine something which could be a lot longer, or wider) and the ability to see where people must be brought together on certain days. It would be practical to have a right hand column called resources to use as a reminder to book tele-conferencing facilities or book flights.

 

EXAMPLES

"To never simplify what is complicated or complicate what is simple." —Arundhati Roy

Gamut

It is my experience that the technical writer needs a wide gamut and many voices. Often one is asked to explain technical complexity to a non-technical audience (tuning a set-top box), yet without being either alienating or patronising. Often you have to be careful not to look dumb yourself, trying to expand on topics in which you are not expert. You need an objective voice, and a subjective voice. You need to be able to write idiom-free international english, and so it goes on, always playing the chameleon.

Voice-over

To write voice-over you must be able to hear it in your head. It helps if you know the actor who will say your words. Don't discount the fact that there are a thousand different ways to say your words. Try to direct the actor yourself, you only have to listen to radio advertising to know just how bad some directors and actors are at interpreting your meaning.

These are some words I wrote for the Pleasant Point Museum and Railway to go over a video that supported their entry in a National tourism competition. They are spoken by Peter Casey whose studio is at Ashburton airport. Right-click to download ppmr_vo.mp3 [7MB].

Instructional materials

We were training people to enter the industry as web designers. I had this idea that the handouts should be disguised as tech notes, and put in an electronic library of reference documents in an attempt to simulate the real world working environment they would be entering. Here is an example tech note, its main features are:

On the same course—Diploma in Web Media, Levels 6 and 7—many of the descriptors we wanted to see were not on the NACCQ framework, so we had to write them. Daryl Foy and myself worked hard to put the various documents together, then Daryl moved on to focus on other things, and I did the final editing, and put it all up for approval. Here are three example descriptors as they were at the proposal stage:

Some topics, like digital audio, challenged the students. To make revision for the assessment more fun I created a first person shooter (FPS) in Flash where the objective was to shoot down the right answer which was flying at you like a sky raider. Making it in Flash and XML was like eating your own dog food which was very hardening for the students. It imported the multichoice questions as XML, which worked brilliantly, and looked like this:

<q>The three bones in the ear are called what?
<a>faceplate</a>
<b>eardrum</b>
<c>ossicles</c>
<d>cochlear</d>
<ans>c</ans>
</q>

<q>The cochlear contains what?
<a>air</a>
<b>fluid</b>
<c></c>
<d></d>
<ans>b</ans>
</q>

I showed it at E-Fest in Wellington (the people in the room next door asked me to turn down the sound). It was very popular with tutors, but the students were less impressed! Download dynatest.swf [5MB] and MA511_50.xml [8K], put them in the same folder (like on your desktop) and play! Note: The application won't play right if it can't 'see' the XML questions file.

Moodle plays a big part these days. It doesn't in itself make the learning experience any better—that still has to be done with a measure of creativity and interactive technologies like Flash—but it does take care of a lot of the organisational overhead like class lists, results, evidence, and reporting. The forums in Moodle are very good, and it is my own experience that discussions are key to successful online learning.

These next three paragraph show my way of doing mock Ruby using CSS. It's a way to annotate a paragraph, and in documents targeted at an international readership it can be particularly useful. If your browser doesn't support CSS you won't really get it and you'll wonder what I am on about. It degrades reasonably gracefully.

theory
Way back in the Windows95 days Ben Schneiderman wrote a paper in which he described his 4-phase genex for excellence. There were variants, but the one I am discussing here is: Collect; Relate; Create; Donate.

application
I explored these ideas in my Diploma of Teaching (Tertiary) and when I am designing learning materials I still use this structure, whether overtly or covertly.

examples
I am creating overt and covert exemplars in Moodle on LMS Farm Courseware. It's a work-in-progress, and if you want a login email me: LMSFarm at gmail dot com.

There is a good little add-on to Firefox called HTML Ruby which renders standard HTML Ruby mark up. If you're working onto an intranet or some other walled garden environment where you can guarantee your readers are viewing the documents in Firefox, then you're cooking. Of course, few writers have this luxury. HTML Ruby mark up fails reasonably gracefully by putting the gloss in plain brackets immediately after the base text.

Research Oriented Development

One of the great things about developing learning objects (LOs) in Flash is the ability to measure the time a remote student spends on each activity. This data can be used to feed back into the design of learning objects, or it can be used in student-user profiling. An example application of this would be Reverse Engineering Rainbows, a topic I have used to introduce fundamental computer science thinking into otherwise touchy-feely multimedia classes.

measuring time engaged
Measuring time engaged.

I had been taking the students straight into a discussion forum without a heap of preparation, and postings were disappointingly thin. I created this little 12-frame Flash LO, nothing fancy, and I noted the time each student spent a) on each frame and b) in total.

With a cohort of 17 students there was a strong correlation between time spent on the LO and the quality of postings in the forum. There was no opportunity to run a control group, so I can't claim an exactly scientific experiment. The logged time data could be used as a tool to work with the relucatant students towards improving their performance in the forums. Performance in discussion forums will be key to student success in the future, as these ways of learning become more widespread.

Dissertation

I have here some example diagrams (in Flash) from my dissertation. It was titled Student-User Modeling In Connectivist Learning Environments and it addressed the difficult problem of how we might assess and credit students who study in distributed learning environments. There was a heap of other incidental stuff about user profiling, and the manuscript was well received.

The "Staircase Mechanism" was an e-toy (self-contained learning device) inspired by the Antikythera Mechanism. This is just a prototype, and has been worked up just enough to show how it might work. Download mechanism.swf [11K]. There was a UML activity diagram which helped describe the Staircase Mechanism. View or download activitydiagram.swf [12K].

The "Domain Expert Console" was a tool domain experts could use to describe "ideal" profiles. In this non-working demonstration (in the real-world it is connected to a database) it is configured for a military recruitment application. There is enough going on here for you to see how it works. The 17 attributes were distilled from the body of existing research. You need a password, it is B9C7. View or download domainexpertconsole.swf [75K].

For anyone who is sufficiently interested in this topic of student-user modeling here is a copy of my dissertation final document. View or download studentusermodeling.pdf [2MB].

 

Stephen Lowe, Timaru, 2009