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.
Related posts:
4 Responses
» Style Guides Writer River
August 6th, 2008 at 10:24 pm
1[...] Style Guides Stumble it! [...]
Tom Johnson
August 7th, 2008 at 2:11 am
2We were talking about style guides where I work lately, and we concluded that we’re all informed about the best practices in the field, so we can allow for a little variation from writer to writer, in the same way that multiple applications in a company don’t have to look exactly alike.
You know, although I first resisted chucking the idea of a style guide, I now like it this way. Sure, we differ a little. One guy likes to write dropdown without a hyphen, and someone else likes to include it. But giving writers this little inkling of freedom in a sea of rules and policies makes writing a lot more fun and less bureaucratic.
I remember my days at another company when we spent months defining our style. It turned out to be a social battle with each other. I wrote about it a long time ago here Social Rules for Creating a Style Guide.
Instead of a style guide, we now have formal help reviews, where we get together and critique and review each other’s help. This keeps us on the same page.
Kumar
August 19th, 2008 at 5:03 am
3Should documents that failed to match with the specified style guide be rejected by the technical editing team?. For example, tables and figures do not match the template used and appear incorrectly throughout the document.
A question and an answer about style guides by Communications from DMN
August 20th, 2008 at 5:20 am
4[...] briefly discussed style guides in a post a couple of weeks ago. The other day, a reader of this blog left the following comment: Should [...]
RSS feed for comments on this post · TrackBack URI
Leave a reply
Blogroll
Past Entries