Technical Writing Guidelines, Style Guides, or Editorial Guides in Technical Writing

This may surprise you, but many style guides are created without it being clear in advance what the purpose of the style guide is: “Let’s write down all of our grammatical rules” or “Let’s pick out all the rules from the tekom guide that we need”. Those who do this create a set of rules that is about as attractive as the house rules of an apartment building. It’s certainly not a good basis for successful implementation.

Instead, ask yourself what problem your style guide should solve.

• Should cooperation with those who offer technical input be improved?
• Do you want to unify the various approaches in your technical writing department?
• Are there stylistic errors in your manuals?
• Or do you want quality assurance to use the style guide as a checklist?

Depending on your aim, this will have an impact on the content and design of your style guide and how it’s implemented in the company’s media.

Most of us are likely to agree that a style guide helps us achieve a consistent level of quality. However, the quality argument often fails to convince those at management level. If you’re hoping to get the resources to create a style guide, the quality argument needs to be examined in a bit more detail: What are you hoping to achieve by improving quality?

• Is the aim to make texts more comprehensible so that the Support team has fewer queries to answer?
• Do you want to make texts shorter and more concise to help speed up troubleshooting for your 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. This helps your company organize knowledge and makes it easier for new team members to get up to speed. In an ideal world, the style guide will become a “full-service package”.

Style guides define what we write and how. In addition to information about how documents are to be structured and laid out, i.e., document quality, they also describe what goes into creating good documentation – the authoring process itself. These include questions such as:

• How much time is there for technical QA?
• What are the conventions for naming files?
• How should a correction be made?
• In which formats should the raw text be delivered?

Besides these basic categories – document quality and the authoring process – many aspects still need to be addressed on a case-by-case basis. The quality objectives and the target group are key. 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 that is.

A guide might not contain any rules whatsoever if the target group is likely to interpret them as patronizing. In this case, the style guide can take the form of a tool describing best practices or recommended wording.

Gear content toward the target group

Depending on the target group, you will need to design your language rules differently when creating a style guide. What may be quite self-evident in your technical writing department may be beyond colleagues working in development. In this case, perhaps you’ll have to work with rules of thumb or else add a little technical explanation to your style guide so that the content is understood. You also shouldn’t underestimate the emotional aspects of a style guide. Those who are not copywriting professionals may sometimes consider it a personal attack if rules are imposed on their writing style, so it’s also important to approach the target group with sensitivity.

The rule of thumb: The more professional the standard of writing of the style guide’s target group, the more stringent and technical you can make the rules. It’s important to test this with the target group. For example, you may sometimes assume that your colleagues possess a level of grammatical knowledge that in reality is beyond them.

Linguistic rules are often abstract and difficult to understand for a layperson, so every guide should contain meaningful examples. These should make it clear in each specific case where the problem lies with certain wording and why the alternatives are better.

Examples should always come from the everyday work of your writing department, ideally from your company. By the way, if you really don’t want to think of an example for one of the rules, or if you can’t find one in your manuals, the rule probably isn’t very relevant.

There are no fixed rules governing the form that the style guide should take. Many companies write their guides as self-contained, linear documents that they release on the intranet as PDF files, which can be a practical and simple solution. If you have a content management system like SCHEMA ST4, 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.

You can also use the authoring assistant to store individual rules in the CMS. This means that the text is checked as it is being written. 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.

When you create a style guide, it’s usually clear which working group will take on the job. But it often isn’t clear who takes care of the style guide once it’s released. However, this aspect is extremely important, because a guideline isn’t a static document. It has to address new topics, modify existing ones, and take on board its readers’ feedback.

That’s why every guide needs a responsible person with enough time to maintain it. It’s also important that it’s clear in the style guide who maintains it and, when this person changes, this should be noted in the guide.