Thu May 12, 2016
Dear user,
We’ve never met, but I write to you every day. Writing to you is my job, but still, I do care.
It starts with the small things. Knowing the frustration of ambiguity, I try to choose the perfect words for you. I painstakingly pore over both our company’s Language Guide, as well as the latest Simplified Technical English specification to ensure I am not using any forbidden words. I also try to use terminology consistently, so that I don’t give the same part two different names.
I also never use the word “utilize”. Although, to my abject horror, one instance did slip through when I copied some text from the Sales and Marketing department.
I then craft the perfect sentences - not too long, not too complex, but with delightful variations in syntactic structure so that you don’t get bored. I polish these sentences so that they are as smooth and round as a river stone, and can therefore be reused in multiple contexts.
These shiny sentences are placed in self-contained topics, as per DITA guidelines. You can get all the information you are looking for, whether it be an explanation or a procedure, just by reading this brief chunk of text. I will never hyperlink you away to other topics, or expect you to hunt for crucial details elsewhere - I know your time is valuable.
I want to make your job easier, because I know you’re a tough guy who does tough work.
You’re a structural engineer who needs to inspect your bridge pylons. You’re a fisherman at sea trawling for your catch. You’re an ROV operator trying to dig an underwater trench. You’re a police officer on a diving team assigned to investigate the latest homicide. You’re “in the Navy now” and your commanding officer just assigned you to berth clearance and underwater security. You’re a treasure hunter who is looking for that lost shipwreck - you know the one with all that Spanish gold on it, like in The Goonies.
However, as much as I respect what you do, I must confess that I’m not wholly altruistic in my motives. After all, the constant companion during my days of writing is not you - it is the words.
Allow me an allegory. The blacksmith who makes a sword for a knight certainly wants the knight to succeed. If the sword snaps, if the weight is off, if shoddy workmanship results in a lethal end for the knight on the battlefield, then both the blacksmith’s pride and reputation will suffer. But the blacksmith’s true love is in the forging of the sword and in transforming raw and molten metals into something greater. What the blacksmith savours more than fame or glory is the slow process of hammering out the metal and continuously reshaping it until a weapon emerges. A weapon that not only performs its function, but could be seen by some as a work of art.
So it is with writing manuals.
This love I have for the craft is why I am not concerned whether you RTFM. In fact, I sincerely hope that you do not ever have to read one of my manuals from cover to cover. I am also nonplussed that my endless word tinkering will go largely unappreciated. You will never wax eloquent over the use of an Oxford Comma while figuring out how to operate your sonar. You won’t go on your smoke break and nod your head sagely at a particularly snappy sentence that says in four words what other less meticulous writers say in fifteen words.
Yet, I am your invisible defender and advocate. I am the guardian angel that you will never know you have. I even go toe-to-toe with software developers over language nuances in the user interface that software developers most certainly do not care about. Software developers only care about the little piece of code they are working on - they’re not concerned with the big picture. Mostly. I’m painting with a large brush here, but this has been my experience most of the time.
Our software lead does write great user experience specifications though - complete with user stories about a stick figure named Joe. Software engineers actually documenting things is an astoundingly rare occurence, however. And if you’re a software developer, I expect you’ll be nodding along in agreement.
So you see, dear user, that I do care. But even though I write to you every day, I do not write for you every day. I write for me. This is true of all writers, no matter who they are and what they write. Do you think Stephen King needs you to buy any more of his novels? The short answer is: hahaha.
Yet, even though we write mostly to amuse ourselves, a rising tide lifts all boats, as JFK once said. Good writing benefits everyone - and it is my gift to you, dear user.
Regards,
Your friendly neighbourhood technical writer