Quotulatiousness

September 3, 2010

Why we still need technical writers

Filed under: Technology — Tags: , , , — Nicholas @ 12:02

Eric S. Raymond has been pleased with the upgrade to his “backup” Android phone, but encountered a very common problem in technology (especially in open source projects, but still too common in commercial products):

As usual in such exercises, the hard part was interpreting the instructions. The hackers who wrote them were trying very hard to be clear, but the result was a thicket of poorly-organized details. I could follow the procedure, but I had to do it almost blind; there was nothing that gave me a high-level view of the process so that I could grasp clearly why each step was necessary and why they had to happen in the order they did. As a result, for troubleshooting I absolutely had to have live help on an IRC channel.

I wish someone would write a bird’s-eye view of the smart-phone modding process. It can’t be that complicated, and I know what’s involved in writing boot loaders for general-purpose computers. Shout to my readers: has anyone done this already, or do I need to put it on my over-full to-do list?

Much of the problem is that folks who are deeply involved in the technical details are often unable to simplify-without-dummifying their knowledge. That’s not surprising, as most are nowhere near as gifted in verbal skills as they are in their own area of technical ability.

June 2, 2010

The (almost) silent scream of the word nerds

Filed under: Gaming, Technology — Tags: , , — Nicholas @ 00:09

The folks who labour (very much) behind the scenes of online gaming sometimes manage to hacksaw through the shackles and post about their anguish:

I’m guessing a large portion of our player base has never cracked open The Chicago Manual of Style. I work in a room full of word nerds. We live and breathe this stuff to the point where we agonize over seemingly mundane things like punctuation, capitalization, and phrasing. For years we’ve gnashed our teeth to the gums while capping common nouns and game terms with every release. Our eyes literally hurt when we edited some copy.

Starting with this article, we’re changing Guild Wars 2 house style to conform more closely to CMS rules. Professions are now lowercased except when used in a title. The same goes for playable races, though nationalities and group affiliations will remain uppercase as is consistent with contemporary practice. It may take a few minutes to adjust to the new look, but we’re pretty confident that you’re a savvy bunch. You don’t need every other word capitalized for emphasis. Context will tell you all you need to know about our lore and game mechanics. Existing Guild Wars 2 articles should be updated to reflect this, but if you catch an error, feel free to let us know.1 Existing original Guild Wars articles and in-game text will retain their legacy formatting, however.

99% of the readers won’t know what the heck you’re talking about, Bobby, but I feel your pain.

August 30, 2009

Always remember to RTFM . . . or else

Filed under: Humour, Technology — Tags: — Nicholas @ 18:59

Life is too short for man pages, but occasionally much too short without them

If you’re not already reading xkcd, why the hell not?

August 2, 2009

QotD: Technical Writing

Filed under: Quotations — Tags: , — Nicholas @ 00:01

Technical writing is perhaps the worst training ground for creative writers. Instead of polishing the descriptive abilities, technical writing is the process of whittling down the prose and sanding off the decoration. A good technical writer writes instructions or descriptions that (ideally) barely even register as you read the words — because the words are merely the carriers of the information you need. If you notice the words as words, you’re being distracted from the primary goal of the reader: getting the information as quickly and as clearly as possible.

Nicholas Russon, 2004-09-09

« Newer Posts

Powered by WordPress