Editorial Guide, Style Guide, Documentation Guidelines – almost every team of technical writers has one or more documents that stipulate what to write and how to write it. Their names may vary, but the requirements they place on a document are similar. Let’s take a peek at what style guides in an authoring environment do and how they’re best created and maintained.
As mentioned above, style guides describe what we write and how we write it. In other words, a good style guide not only contains information about how documents are to be structured and laid out, i.e., document quality, it also provides information about the process by which good documentation is created – the authoring process itself.
Besides these basic categories – document quality and authoring process – many aspects still need to be addressed on a case-by-case basis. Since when determining what to put into a style guide, the target group for the guide is just as important as the quality objectives. If the users of your guide only occasionally create documents, a rule stating, for example, “Avoid noun-verb combinations” makes little sense, as the chances are your readers will not even know what a noun-verb combination is.
A guide may also not contain any rules whatsoever, if, for example, the target group is likely to interpret them as patronizing. In such cases, the style guide can take the form of a tool describing best practices or formulation recommendations. The rule of thumb is therefore: The more accustomed the target group for your style guide is to writing, the more the rules can be formulated in a binding and technical manner. What is important, however, is that you also test this premise on your target group. For example, you may sometimes assume that your colleagues possess a level of grammatical knowledge that in reality is beyond them.
Similarly, there are no firm rules governing the form that the style guide should take. Many authors write their guides as continuous, linear documents that they release on the intranet as PDF files. There’s nothing to say this is not a practical, low-cost solution. However, in situations where a CMS is being used, another option is to maintain the style guide as part of the system and to make use of the multiformat output options of the CMS.
Some rules are best left to the authoring support features in CMS and checked during the writing process, rather than trying to formulate them all in a document. The most important thing to remember is that any rule that can be automatically checked as you’re writing (terminology, syntax, etc.) belongs directly within the system and not in the style guide.
Finally, we have to ask ourselves, what are the benefits of all this? It’s clear that most of us are likely to agree that a style guide helps us achieve a consistent level of quality. However, the quality argument oftentimes fails to convince those at management level. If you’re hoping to obtain the resources to create a style guide, the quality argument needs to be examined in a bit more detail. What is the purpose of this quality? Should it make the text more comprehensible so that the Support Team has fewer queries to answer? Should it make the text terser and more concise to help speed up the troubleshooting activities of our service colleagues? Demonstrate the effects of improved quality, so that the decision-makers are made aware of its benefits.
And don’t forget: besides improving the quality of the documentation, a good style guide also delivers advantages at the process level. It streamlines document production, ensures that work proceeds in an orderly manner, and that everyone involved in the process knows what role or which co-worker is doing what, when, and how. It also contributes towards the organization of knowledge and makes the familiarization process for new team members easier. In an ideal world, the style guide will become a “full-service package”.
Moderatorin Kerstin Berke und Marketingspezialist Philipp Eng sind das Duo vor und hinter dem Mikro der „Doku-Lounge“…
