Ever been to the Klingon homeworld? No? Well, it’s a fictional planet populated by members of a warrior race devoted to honor and combat.
Not a whole lot of readin’ and ‘ritin’ going on in Klingon salons, but even Klingons need documentation. Documentia Inc published a Top 16 List of Things Likely to be Overheard in a technical publications department unfortunate enough to be staffed by Klingons. I’ve summarized five of the most instructive quotes, along with my comments, to share with you.
DISCLAIMER: Klingons are a violent people, and even though my summary omits the semi-gory parts, infowriters with delicate sensibilities may find the war-like imagery unsettling. Of course, if you’re not prepared for an occasional skirmish – with user-unfriendly, technogeek-centric software, with complex and confusing procedures, with inflexible, outdated style guides — you may want to consider a less hands-on kind of writing.
- Quote #3: I will return to the homeworld and my documentation will arise triumphant in the STC Documentation Gauntlet, leaving all others drowning in their own dangling modifiers. It will be glorious!!
Infowriting Lesson: My documents will not be run-of-the-mill, good-enough-for-government-work mediocrities with logical lapses, sloppy syntax, and garbage grammar. I will produce the most useful documents I possibly can.
- Quote #5: These software specifications are for the weak and timid!!
Infowriting Lesson: Point out deficiencies and suggest ways to improve clarity in the specification for the product you’re documenting. Avoid vague, non-quantifiable specs. Make sure the functional specifications are spelled out from the point of view of the user … not the engineer. Unless, of course, you’re documenting a product for engineers to use.
- Quote #10: Passive voice is a sign of weakness. Its elimination will be quick.
Infowriting Lesson: My infowriting should be direct, forceful, and to the point. No passive voice. Not many abstract nouns. Straightforward sentence construction. No weasel-wording.
- Quote #11: Proofreading? Klingons do not proofread. Our documents are purified with pain-sticks that cleanse them of impurities…..and
Quote #13: A TRUE Klingon warrior riddles his document with bullets, leaving it to beg for mercy.
Infowriting Lesson: The words that flow from my pen (or more likely across my monitor screen) are not sacrosanct. My documents are not holy writ; they can and must be subject to quality control. And they require more than proofreading. No matter how much psychic pain I feel during the process, I will purify my documents ruthlessly, following the rule of C’s: making sure the document is clear, compelling, coherent, correct, and consistent. Bullet wounds inflicted by editing always heal.
- Quote #16: Our users will know fear and cower before our suite of manuals and online help! Ship it! Ship it and let them flee like the dogs they are!
Infowriting Lesson: This attitude (exaggerated Klingon-style here for effect) shows up in infowriting as:
– A lack of attention to readers’ needs
– A focus on technology rather than usability
Its inevitable result? Manuals and other documents that are hard to read and even harder to use as guides for getting work done.
