Communications from DMN

When it comes to style guides, I’m of two minds. I know that they’re useful, and provide a framework for creating consistent documentation. On the other hand, I’ve seen far too many writers and editors become blinkered by the style guide — it’s an all-or-nothing proposition.

During my time at The Company That Shall Not Be Named, a technical editor went ballistic on me because I put Canada before United States when describing the choices from a geographic location list. The style guide, a sacrosanct tome, stated that United States always comes first. It didn’t matter that I was describing how the list looked in the GUI.

When I said that the company’s style guide was a tome, I meant it. The book was several hundred pages long. A bit too big and bulky in my opinion. I’ve never encountered an in-house guide quite that large, but some have come close. And others have been pretty brief.

Aside from some of the well-known style guides, I’ve encountered very few that were any good. That said, here are some of the more interesting and useful style guides that I’ve run into recently:

• Documentation Style Guide for OpenSolaris
• mozilla.org Documentation Style Guide
• Apple Publications Style Guide
• OpenBravo Documentation Style Guide
• Style Guide for NASA History Authors and Editors

Do you have a favourite style guide? Tell us about it by leaving a comment.

I don’t know about you, but in recent years most of the documentation that I’ve written has been distributed electronically — as PDFs, online help systems, HTML, and even on a wiki or two. The last time I held a printed and bound guide that I’d written in my hands was a couple of years ago. And, to be honest, it was a strange feeling. In a good way, though.

From what I’ve seen, and the technical communicators with whom I’ve chatted, it seems like printed documentation is dead. If not dead, then dying. Which is a good thing in many ways — especially when you consider the resources used to print and bind a manual or set of manuals.

But there are situations in which a printed manual is a necessity. I was reminded of that when I talked with Teresa Mulvihill-Talbot at DocTrain West in May. During our conversation, Teresa mentioned technicians in the field repairing printers. Obviously, in that type of situation, hard copy documentation is a must.

Why not electronic docs? People in the field might not have wired or wireless network access, so getting to a central repository of information will be impossible. Sure, the could have the documents on a laptop or a PDA but there might not be enough space for these devices in a work area. On top of that, there are the ever-present dangers of the battery running dry and not being able to plug in, and losing or breaking the device.

Printed manuals can be lost and damaged, too. But it’s cheaper to replace them than an expensive piece of electronics. And let’s be honest: not everyone is comfortable reading on a screen.

Thoughts? Feel free to leave a comment.