November 26, 2008

Tech Writing = OCD?

Over at Ars today, Erica Sadun gives thanks for the iPhone SDK's documentation:
Thank you for the kick-ass SDK documentation. I know you have employed many OCD victims who would otherwise be wandering the street picking up litter and tidying our world and instead aimed them at creating precise and glorious help pages. Sure, it takes about five years to download each API update but oh, the beauty of it when it finally is installed!
I've often had a similar thought about my team. The LabVIEW Documentation team consists of some of the most detail-oriented people you will ever meet. We debate using "attend" vs. "participate in". We agonize over "both" vs. "either". We spend half an hour brainstorming the placement of a level 2 heading and worry over its effects on the help file table of contents. We nitpick over parallelism in bulleted lists, consistent descriptions of everything, and so many other things. We pester developers with questions, trying to nail down that one perfect way of describing a feature.

And the worst part about it is -- we like it :-) (Well, at least I do.)

I don't know if it qualifies as OCD, but I'm sure there's some sort of term for how we are. "Grammar Nazi" comes to mind, but that's really pejorative and, to me, relates to Web forums where you're correcting the grammar of strangers in a situation where that activity is not expected or encouraged. "Anal-retentive" could be another description, but again, that feels pejorative :-) "Detail-oriented" is good, I suppose. I would say that we just care a lot about presenting information in the most helpful, unambiguous way possible.

Ahh, see, I'm doing it again!

November 17, 2008

Apple Releases Sept 2008 Style Guide

Hat tip to Daring Fireball (an excellent blog that I read despite not owning any Apple products) for the news that Apple has released its 2008 style guide.

When 1,000 writers are writing technical documentation for 2,000 products, consistency is very important, even down to the correct capitalization and noun strings used to refer to specific parts of software or hardware. Style guides keep everyone on the same page, so to speak, and help reduce confusion among customers when they read about "front panel objects" versus "front panel controls" versus "front panel nodes". Are those the same thing or are they different things? You, as the customer, should not ever have to wonder about this. The style guide helps mitigate these issues.

Of course this means that, as a writer, your range of expression is restricted. You cannot write everything the way you want to. There is very little room for creativity and personal style. You must submit to the whims of the company style guide. Some people find this situation constricting and frustrating. So it's important that technical writers have a say in how their style guide is constructed. It must not be an authoritative top-down mandate from on high. It must not change every two weeks at the whims of a tyrannical editor who decides that it's okay to split infinitives in January but not in March.

No, the style guide must be collaboratively constructed and able to be modified by anybody. If you have 1,000 writers in the company, you can introduce some representation into the process to make things easier; that's fine. Form a style guide committee comprised of members from different groups. Regularly rotate through representatives. Non-reps can submit their own issues (as bug reports) to the committee and argue for them in front of the committee, who will decide. Yes it sounds very, well, Congressional. And it takes a lot longer than simply deciding things. But style guides shouldn't change too often anyway -- that's one way to confuse and frustrate people. And if you're going to enforce a process on somebody, at least give them a say in how that process is constructed. You don't have to agree with their suggestions, but you do need to give them an avenue for dissent. Otherwise, all the little frustrations will build up, and the only opportunity to release those frustrations will be to quit (or move into Marketing!).

After all, you hired smart people, right? So put their intelligence to use.

And by all means, encourage new hires to look at the style guide. They will find all those weird little issues and inconsistencies that you never noticed because you've been dealing with the same document for six years.

Finally, remember that there's a reason it's called a style guide and not a style rulebook. There will be situations in which it makes more sense to go against one of the guidelines rather than blindly following the style guide. Recognize these situations and learn to make your case for why, in this case, splitting an infinitive is okay. Remember that the number one decider of any situation is "will this help the customer understand what we're talking about?"

Note here that I'm talking about style guides for technical writers. But my ideas could just as easily apply to coding conventions or "best practices" documents for programmers.