Posts about “Documentation”
So you work at a big hi-tech company and you have questions. Lots of questions. But your manager is in yet another meeting and your deadline is looming. Who do you turn to? Why, your friendly, neighbourhood technical writer of course. Here’s why:
Your technical writer may have written a 500 page manual on how your product works but you sure don’t have time to read that beast. Why not ask the author directly?
I say eleven, because Ben Minson came up with this excellent list of seven plus four more on his blog, Gryphon Mountain. His list gives reasons why a company should hire a technical writer. Check it out if you need to justify your existence or if nobody has fought through the cobwebs to your cubicle in a while and you suspect the engineering department has forgotten about you. Or maybe you need to explain what-it-is-you-do-exactly in a job interview.
Wired magazine has some interesting pieces this month. Well, every month is pretty good, but writers might appreciate this behind-the-scenes look at how an article is assigned, written, edited, and designed. You can read the email correspondence between author and editor, and get an idea of how to pitch your story idea to a magazine. Great stuff.
Also, technical writers might get a kick out of this photo essay of classic instruction manuals.
I thought it was high time for an update on the first two weeks of my contract. As I alluded to previously, the project I’m working on right now involves the design of a new phone. It’s a complex system with many components, and is rather hush-hush at the moment so I can’t really elaborate on it. Thus far, much of the system behaviour has been decided upon verbally, which is where I come in.
DocTrain chugged along today and picked up some speed with a heavy emphasis on social media. As with yesterday’s post, I’ll give you the skinny and the slides on each presentation as well my pick for ‘what’s hot’.
Great people, good food, and leading-edge content. Kudos to the organizers and to the Marriott Pinnacle for hosting this terrific event. And a huge thanks also to the Westcoast STC for the opportunity to attend.
Today I attended a pre-conference workshop on Simplified Technical English (STE) at DocTrain West. Berry Braster, director of Tedopres, presented the benefits of writing documentation using standardized, unambiguous English, especially when materials are being translated into other languages.
The implementation of STE involves developing a company-specific dictionary and using documentation software to aid in the mechanical side of ensuring uniformity of language across the board. The goal is to ultimately reduce costs and facilitate quality assurance.
This conference kicked off in Vancouver today and is the place to be if you’re facing content management issues in your professional life as a technical writer, or if you want to stay on the leading edge of developments in the field. Each day has a specific theme. Day 1 (today) is about content, day 2 about technology, and day 3 about user relationships. I’ll be volunteering there the whole day tomorrow, and will tell you all about it later (if you’re going, be sure to say hello).
There is nothing more sickening than a piece of writing bloated and weighed down by heavy jargon and confusing language. Call it what you will - jargoneze, legalize, bureaucrateze, or just plain gobbledygook. If you’re spreading this kind of rot, you’re a language killer and should be tried and condemned by your peers as such. In his essay, _Politics and the English Language_, the great George Orwell calls us to vigilance:
When editing technical documents, how aware should you be of regional differences in pronunciation? Here is an interesting article on the subject by Brian Forte. Forte raises the following issue regarding the usage of an indefinite article with initialisms:
How do you pronounce an initialism like HTML?
I was taught English in public Australian schools of the 1970s. So I was taught aitch rather than haitch. Which means I pronounce ‘HTML’ with an initial vowel sound and I write ‘an HTML page.