Fear, loathing, and the editorial style guide


Does my organization need an editorial style guide? It’s a question I hear quite often as a technical writer.

My answer to the style guide question is “Yes, organizations do need a style guide, but it shouldn’t dominate the documentation development life cycle.” With the prevalence of online documentation and the web to deliver information plus more iterative development and launch cycles, the style guide should foster productivity and consistency not stand as a roadblock in the way of technical writers and training developers making deadlines.

My concept of a style guide

Over the years, I’ve become a fan of more lean style guides. Cover just the basics of product naming, corporate branding, and anything industry/audience specific and leave the style guide at that. The document should be in a quick reference format, and all document authors should be briefed on the style guide before being let loose on a technical writing project. Sure there are many things that such an approach to style guides may leave out, but that is where standardizing on an industry style guide like the Microsoft Manual of Style for Technical Publications, AP Style Book, Yahoo Style Guide, or ReadMe First!.

Decision-making about styles

Indecisive decision making over stylistic issues is boorish and counterproductive and in the end, there is no benefit to the document, project or end client. Running with a lean style guide means the occasion may arise where a stylistic decision is made on the fly.

A lean style guide only works when a senior writer or editor is given ownership over stylistic decisions. When such a decision is made it should then be documented in a style guide update. Having one “keeper of the style guide” avoids dragging out stylistic decisions by committee.

Publishing your style guide

These days, do yourself a favor and skip Microsoft Word for your style guide and take it online. I’ve had good luck with Atlassian Confluence cloud for style guide publishing. You can set up a space that’s searchable and can set the access privileges to your writers or even open it up to the public Internet.

Know the audience

Just like writers need to understand their audience for the documents they are writing, this understanding needs to carry over to the style guide. If the style guide serves up too many items that are lost on the reader of the end documents, then the style guide is ineffective.

Likewise, if the writers asked to follow the style guide have issues understanding it then the style guide also fails.

If the style guide is full of contradictions, it also fails.

The style guide is a supporting document, and when that is forgotten, the style guide fails.

An earlier version of this post appeared on my personal blog.

Will Kelly is a technical writer and analyst based in the Washington, DC area. He has worked with commercial, federal, higher education, and publishing clients to develop technical and thought leadership content. His technology articles have been published by CNET TechRepublic, Government .Computer News, Federal Computer Week, Toolbox.com, ZDNet.com and others. Follow Will on Twitter:@willkelly.

Image by Markus Spiske via Unsplash.com

Read More

Leave a Reply

Your email address will not be published. Required fields are marked *