1.       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? Your technical writer probably knows more about the product than anyone else at the company.

2.       Who is constantly interviewing marketing and upper management for the latest product definitions and behaviour? Not you.

3.       When Quality Assurance finds a bug they don’t cross-check your code, they check out the documentation. Guess who wrote the documentation.

4.       Does your product spec give little insight into the user interface? Your technical writer thinks like a user. They do not think like you. Trust me on this.

5.       Or maybe you have a really great idea for a product improvement but the thought of writing a proposal to the decision makers puts you off as much as writing an essay in English class did. Technical writers love writing essays. In fact, if they’re on-board with your idea you cannot find a better advocate.

1. End users need documentation.
2. Technical communicators look at the product with a user perspective.
3. Technical communicators help with quality assurance.
4. Having quality documentation reflects positively on your organization.
5. Documentation provides a record.
6. Documentation saves on support costs.
7. Technical writers have a versatile skill set.
8. Technical communicators’ information gathering gets the team to think critically.
9. Technical communicators are specifically trained.
10. Technical communicators lighten the load.
11. Technical communicators can provide training and support.

I agree with all these points. The only thing I’d add is that the audience for technical documentation can be far more diverse than just the end user. Engineers, marketing managers, stakeholders, product testers, and just about everybody involved needs the goodies. Documentation is important at all levels of the production cycle.

Also, technical writers might get a kick out of this photo essay of classic instruction manuals. What I found interesting was what Dan Winters, the photographer who compiled these, had to say: "I actually think that modern manuals are unreadable," Winters says. "Visually speaking, they probably peaked in the ’30s." What rot. Seriously – is this guy part of the MTV generation or something? End-user documentation has never been cleaner and easier to understand. In fact, most help is migrating to interactive web-based apps that even a child would coo at. I understand he’s speaking as a visually-biased photographer – not a writer, but the overly intricate diagrams in his photo essay (as cool as they are in a retro sort of way) hardly represent the peak of information architecture.   

The goal is to provide the engineers with a base line so that they can move forward with the design process. This means I’m also creating screenshots of what the man-machine interface (MMI) will ideally look like. I’ve been doing these in Photoshop, but there is talk of moving to a program called Axure, which offers a much richer functionality and the ability to create master modules (so that you don’t have to re-generate a hundred screenshots every time a small change in the MMI is made).

All in all, it’s very interesting being involved at this stage of product development, although I was hoping to do some end-user documentation as well. At this point that looks doubtful as that’s the tech writer in Oregon’s baby.

Some of the work is a bit dry – for example, today I was determining how many characters to allocate a word for translation. The English interface has to be translated into French and Spanish, but there is a limited amount of pixels on the display screen on the phone, so I had to figure out how much wiggle room to allow the translators, in case their translation of “Answer”, for instance, turns out to be a five words long.

The company culture is quite rad – lots of barbeques and once a month there is a social with buckets of beer and an assortment of greasy food (no organic juice like at alive unfortunately). In the lunch room is a sweet gaming setup -two widescreen hi-def TVs – one hooked up to an XBOX 360 and the other hooked up to a Wii. On the table sits a couple of Guitar Hero axes and steering wheel controllers. There’s also a pool table, ping-pong table, and foosball. Basically a geek’s paradise! 

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.

Here’s the best of the rest:

Document engineering in user experience design
Robert Glushko (University of California at Berkeley)

With little collaboration between designers (front end) and information architects (back end), the result is a poor user experience. A brilliant mind, Glushko coined a new term today: the content choreographer.
What’s hot:  Doc or Die

| View | Upload your own

Social media 101: Now everyone’s a technical writer
Darren Barefoot (Capulet Communications)

From Youtube to Twitter to Facebook, social media is about two-way conversations, collaboration, sharing, community, transparency, and authenticity. It also means we have to relinquish control of our content.
What’s hot: Web 2.0 in plain English

View slides on scribd

Changing the rules of the game for the benefit of the user
Joe Sokohl (Keane, Inc.)

In his talk, Joe emphasized knowing your end user – especially when training customers. Qualitative research is the key to giving end users what they want, not what you think they want.
What’s hot: The Kobayashi Maru approach to solving problems

| View | Upload your own

How an author and editor used a wiki to write a book
Stewart Mader (Atlassian)

Stewart wrote his book using only a wiki. He found that communicating with his editors using a wiki was far more efficient than using email.
What’s hot: WriteRoom (Mac only…grrr!)

The many-armed starfish: today and tomorrow in social media
Darren Barefoot (Capulet Communications)

I can’t get enough of Darren – he’s a terrific speaker. He expanded on social media tools and explained which ones were most effective for use in marketing strategies.
What’s hot: Brightkite

What technical communicators need to know about flash
Sarah O’Keefe (Scriptorium Publishing)

Flash is finicky, but useful if you need to explain difficult concepts using animation. From motion to shape tweens, we got the basics in this tutorial.
What’s hot: Brain games

Living multiple lives: The new technical communicator
B. Noz Urbina (Mekon)

In the closing keynote, Urbina gave practical advice on how to create documents more efficiently and save your company money (the reason companies pay for employees to fly to these conferences in the first place).
What’s hot: Fly me to London

| View | Upload your own

That’s a wrap. Now go outside.

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. If you’re interested, here’s an abbreviated version of Berry’s powerpoint presentation:

| View | Upload your own

I found this presentation quite interesting, especially as there is little standardization when it comes to documenting software. Berry actually dismissed Microsoft’s style guide, and even the Chicago manual of style, as incompatible with the goals of STE, but did commend them for the attempt. Some of the audience thought that STE could become too stilted and robotic. Personally, however, I could see the merit of choosing vocabulary, for example, that is completely unambiguous when it comes to reducing workplace accidents.

A case in point – a manual in the aviation industry asked the mechanic to “cut the power” (ie. turn it off), whereupon a mechanic literally cut a power-line with sheers and died from electrocution. 

Highlights? The future of XML publishing, the new Quark dynamic publishing demos, social media, mobile content management , and of course, the fabulous food.

A man may take to drink because he feels himself to be a failure, and then fail all the more completely because he drinks. It is rather the same thing that is happening to the English language. It becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easier for us to have foolish thoughts. The point is that the process is reversible. Modern English, especially written English, is full of bad habits which spread by imitation and which can be avoided if one is willing to take the necessary trouble.

Orwell was concerned with the use of English to deliberately mislead and confuse, but what about readability? How readable is your writing? Many handbooks and journals on technical writing stress readability as highly desirable and advocate the use of readability formulas. I’m referring to Flesch’s reading ease scale and Gunning’s Fog Index. These formulas calculate how many syllables are in your words and how short your sentences are and tell you if you’re a good writer or not.

Unfortunately it’s not that simple, and if you’ve ever played scrabble, you’ll know that there’s plenty of really obscure two letter words out there. So a low syllable count doesn’t always indicate readability. Neither do short sentences; sometimes short sentences break thought flow and are easier to understand when connected to other sentences through a logical connector.

The moral of the story is: Don’t use computerized readability formulas to evaluate a piece of writing. The only way to determine whether a piece of writing is good or not is to consider the audience. What is the writer’s purpose and who is the writing intended for? If you bear these two questions in mind, evil, manipulative writing can quickly be rooted out. The plain language movement advocates this approach:

Plain language is language that is understandable. What is clear, or what is plain to your intended audience, can only be decided by the audience.

So plain English is not simple baby two-syllable English. It is simply a version tailored to be as readable as possible for those who you’re writing for, whether they be ESL students or Javascript programmers, who might be quite comfortable with a few five syllable words in every paragraph.

Anyway, all this is a preamble for a new segment I’m going to unveil in the next post: The product riddle: What am I anyway? Stay tuned.

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

If I’d gone to a private Irish Catholic school, however, I would have been taught haitch and would, naturally enough, think ‘a HTML page’ is correct.

More generally, haitch is standard in Hiberno-English and is a way for disputing Protestant and Catholic Northern Irelanders to distinguish themselves from each other.

So, if I insist on ‘an HTML page’ I’m telling 4.5 million English speakers their way of writing and speaking is wrong, or non-standard at the very least. And I can’t reveal accent by writing ‘an ’TML page’ because it’s a technical document, not a novel.

Seriously though, how many Irish Catholics are going to tear up their Linux manuals in disgust after discovering a pernicious “an” embedded in the text? It’s nothing personal. Technical writers are just following a style guide. Some tech writers will go with “a html” because they look at the expanded form of the initialism. So “a Hypertext Markup Language Page” would be written as “a html”. Does that mean everybody who pronounces “h” as “‘aitch” (which is the majority of the English-speaking world) should label these writers as hate-mongering, prejudiced Irish Catholics?

It all comes down to schisms in pronunciation. Yet, in today’s globalized world, there isn’t much room to argue with the majority.