Do organizations need technical documentation style guides? It’s a question that rises on online forums every so often. Today’s ever-tightening workplace budgets should also put the role of the technical documentation style guide under the spotlight.
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 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 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.
This only works when a senior writer or editor is given ownership over stylistic decisions. Any stylistic decisions must be documented in a style guide update. Having one “keeper of the style guide” avoids dragging out stylistic decisions by committee.
Know Thy 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 tasked to follow the style guide have issues understanding it then the style guide also fails. If the style guide is full of contradictions, it fails again. The style guide is a supporting document, and when that is forgotten, the style guide fails.
The style guide should be a guide not an obstacle to publishing documents.
Hi! My name is Will Kelly. I’m a technical writer and analyst based in the Washington, DC area. I’ve worked with clients like NetApp, Dell, and Neustar to develop technical, training, and thought leadership content. My articles have been published by IBM Mobile Business Insights, TechBeacon, CNET TechRepublic, Network World, Toolbox.com, ZDNet.com, and others. Follow me on Twitter:@willkelly.