ffeathers — a technical writer’s blog

These “Yard table assemblage instructions” were included with a garden table we bought. Actually, the structure of the guide is good. There’s a list of parts and then the “how to”. It’s just the language that needs a bit of tender loving care. I love the way it degenerates towards the end, as if the poor author just gave up because it was too hard.

Assemblage parts:

1.One piece of iron flower pattern glass (in midst have a hole).

2.Four table feet.

3.Two fixed stators.

4.Eight screws.

5.Eight screw caps.

Assemblage method:

1.Use the screws and screw caps screw down the table feet and fixed stators.

2.Table top is upward.

3.half-round plastics of under the table top direct against the table feet, Then press it down.

We did manage to assemble the table with no trouble.

Today I walked past two women just as they saw each other on a street corner. This is the snippet of conversation I overheard:

A: Hello!
B: Hello, is that you?
A: Yes.

They both thought this was a perfectly sensible exchange, but I had to chuckle as I went out of earshot.

Why can’t our documentation be as directly and succinctly understood? Because we don’t know the subtext for every passerby who comes across one of our pages.

The title of this blog post has a double meaning, because I am writing it from my iPhone while sitting on the bus. Yes, it’s me.

Clarity is everything, in signs as well as in technical writing.

This sign doesn’t pull any punches I guess you could call it the Manly Council version of “Life, the Universe and Everything”:

Say it like it is

Transcription (with adapted capitalisation and punctuation):

MANLY COUNCIL

Beware. Unstable rock formation. KEEP OUT. If you choose to proceed beyond the fence there is risk of serious injury through collapsing rock including but not limited to serious neck and spinal injuries and even death. By Order, General Manager.

“Serious injury… including but not limited to… death.” Oh dear.

And I particularly like the last bit: “By Order, General Manager”. It adds just the right touch of bathos.

I’ve just finished re-reading The Fountains of Paradise by Arthur C Clarke, published in 1979. A lot of people know him as SF-writer extraordinaire. Some would recognise his visionary engineering insights too. We might even acknowledge him as a pretty reasonable technical writer But did you know he was into Web 2.0 as well?

In The Fountains of Paradise, chapter 34 “Vertigo”, there are a by-the-way few paragraphs where the author explores the “development of global information systems” that might have occurred by the year 2142, when the book is set. He guesses there might be some automated solution for annoying tasks like sending birthday wishes to all your friends And then he goes on to say:

But the same technology that had eliminated one set of tasks had created even more demanding successors. Of these, perhaps the most important was the design of the Personal Interest Profile.

Most men updated their PIP on New Year’s Day, or their birthday. Morgan’s list contained fifty items; he had heard of people with hundreds. They must spend all their waking hours battling with the flood of information…

Hallo syndication, RSS and information overload. Alas, the ultimate engineer did not mention a solution to the problem. Perhaps we will have found one by 2142.

Fountains in Darling Harbour, Sydney:

Documentation answers all the big questions of life: How did I get here? What’s it all about? How do I do it? What’s next?

This leads to the inescapable conclusion that documentation is at the centre of the life, the universe and everything.

Even if all it says is: ‘Wrong way — go back’.