"Wherever there's collaboration, you need rules."
When it comes to creating technical documentation, such rules are often laid down in an editorial guideline. How should such a guide be structured? What are the essential elements and what must be taken into account when introducing them?
We've summarised the answers to these questions (and all other key points) for you.
Why an editorial guideline at all?
In most cases, technical editing means working as a team, often across different locations. It's not always clear which standards and rules are actually used to create the instructions. In addition, technical editors unconsciously bring their own editorial style into the process.
Especially in tricky situations, they almost automatically come up with individual solutions that have often proven successful in the past. This isn't fundamentally wrong and can certainly help to deliver a good end result.
In the long run, however, this approach inevitably leads to inconsistencies in the documentation and dangerous methodological proliferation – an absolute no-go in the documentation world. The remedy is a central set of rules in which all specifications and decisions for the effective creation of technical documentation are documented – the editorial guidelines.
What concrete advantages do editorial guidelines offer?
Clear and comprehensibly formulated rules make the work of technical editors much easier. This sounds logical! Are there any other advantages that result from the introduction of editorial guidelines?
In our experience, the following three aspects are of critical importance:
1. increase the quality of the documentation
Consistency is an essential quality feature of good technical documentation. It helps users to absorb the information more easily and thus increases the comprehensibility of the instructions. However, the concept of consistency is not limited to linguistic specifications for formulations and terminology.
The motto for the structuring and design of the information (and for the overarching procedures in the editorial process) is also: clear guidelines and a uniform approach are the be-all and end-all. An editorial guideline thus creates an important prerequisite for professionalising technical editorial work and achieving a consistently high level of documentation quality.
2. cost savings
The introduction of an editorial guide is also more than sensible from a business point of view. The main advantage: In a technical editorial department that works according to precisely defined guidelines, coordination efforts caused by ambiguities and queries can be significantly reduced. This increases throughput efficiency and ensures higher productivity for the department as a whole.
In addition, it's only with an editorial guideline that the required degree of standardisation can be achieved, which is necessary to systematically reuse content once it's been created. This reuse pays off – both in the creation process and in the subsequent translation of content.
3. improve collaboration
Unclear processes, undefined responsibilities or outdated document templates: Negative factors such as these can have a huge impact on collaboration within the team and on employee motivation. An editorial guideline helps to make editorial knowledge transparent and to make it available to all colleagues. This creates a uniform knowledge base in the team, and linguistic doubts and other contentious issues can be easily resolved.
The onboarding of new employees is also much easier with clear rules. This is particularly helpful in large technical editorial teams that are distributed across several locations or are additionally supported by editors from an external service provider, for example.
What is defined in an editorial guideline?
Good editorial guidelines regulate and standardise the essential aspects of creating technical documentation. This applies to all levels of the process (i.e. from the basic procedures at a higher process level; who does what – to concrete formulation rules at the linguistic level). What exactly is defined in an editorial guideline is logically individual and varies from department to department.
Basically, the contents of a guideline can be divided into the following four topics:
Processes and Procedures
A guide goes through various steps from planning to publication. In addition to the technical editorial team, a wide variety of process partners with their own unique tasks are involved in the individual project phases, such as design, development, quality management, editing and translation. To ensure that all the cogs mesh correctly, the basic processes must be clearly defined and known to all those responsible.
The first step is therefore to clarify the central issues surrounding project management. These can be, for example:
Who assumes which tasks within the framework of the processes? Who are the appropriate contact persons? How is the time schedule of a documentation project defined? Who has to deliver which information on which date and/or time? Which tools are used and how is information exchanged between departments? How are responsibilities regulated in the case of absences (e.g., in cases of illness or vacation)?
Design and Structure
Whether they're assembly instructions, a software manual, or the topic in an Online Help system: For each information product, the content should be structured according to uniform rules. How far these structural guidelines go depends, of course, on the framework conditions of the respective technical editorial department. An established procedure is to define the basic structure of frequently used content modules such as safety instructions or action sequences.
If a traditional word processing tool is used in the department, there are usually already sample templates for individual document types or content modules. These templates should be stored in a central location, and the storage location should be included in the guidelines.
If, on the other hand, an XML-based CMS is used, references to permissible or preferred element types can be listed in the guidelines, for example. If the technical editorial team also has a fixed concept for the uniform modularisation of the content, it makes sense to integrate this into the guide as well.
Writing style and Formulation
Rules for consistent authoring form an important part of every technical editorial guide and ensure the consistency of the documentation at text level. This includes, among other things, the correct use of abbreviations and subject names within the context of terminology management. It's important to note that the actual terminology list is not included in the guidelines, but is managed in an external, dynamic document. However, the reference to this list and all additional information on terminology management belong in the guide.
Another key aspect is the rules on style and wording. Often, these writing rules are presented in the form of concrete instructions for action, as the following example shows:
Avoid Noun Phrases
Nouns have to be translated (subconsciously) into verbs by the reader and thus have a tiring/draining effect.
Layout and Graphics
What are the guidelines for visualisation and layout? Here, too, a lot depends on which tool the team uses. In the database-supported CMS, most of the work in terms of design is already done by the system. Here it can be useful to explain the style sheets required for certain document types in more detail.
In the case of traditional word processing, reference can be made to templates and samples, or specific details can be provided about typography, type area and other layout settings. For the creation of uniform graphics, it's also essential to define an illustration concept. This includes aspects such as graphic style, colour scheme, permissible perspectives, and defined characteristics of pictograms, symbols, and icons. This creates a consistent visual language and makes the creation process much easier.
It may also be necessary to comply with other Marketing specifications, such as those relating to corporate design/identity. These are often set out in a separate style guide, which should be referred to in the editorial guidelines.
When is an editorial guide worthwhile?
In short, an editorial guide can be useful at any time and for anyone involved in the creation of technical documentation. This is just as true for a large technical editorial department with 10 employees and additional service provider support as it is for a small two-person team that creates all manuals on its own. In general, it can be said that anyone who prepares the central regulations and specifications for the documentation process in a comprehensible and precise manner reduces effort and creates security – and prevents situations in which, for example, a key subject matter expert disappears at the last minute, and valuable expert knowledge is no longer available.
Our experience has also shown that the introduction of an editorial guide can be particularly useful in certain situations:
- When a reorganisation takes place in the company that has a direct impact on the work of the technical editorial department (e.g., through the introduction of an agile working method in R&D).
- When a change is made from classic documentation creation in a word processing program to a modular method of working (through the introduction of a CMS).
Are there also disadvantages?
Where there's light, there is of course also (some) shade. As with all process optimisation measures, an initial outlay must be expected for the editorial guide until everything has settled down and the new regulations are effective.
Before the actual creation of the editorial guide can begin, the following steps, among others, should be carried out during a concept phase.
- Analyse processes and quality of documentation.
- Identify regulation, revision and optimisation needs.
- Identify editorial guide representative and form editorial guide team.
- Determine time requirements.
- If necessary, seek external advice.
With the right preparation, however, even this initial effort is manageable and shouldn't be an argument against introducing an editorial guide.
In addition: In the first attempt, not all aspects of the process have to be covered 100% and immediately bundled into a final set of rules. Even after the introductory phase, the "editorial guide" project is not finished, but lives and grows, together with the process.
How should the editorial guide be published and made available?
The classic PDF
There are no fixed rules for the publication and provision of an editorial guide.
Many technical editorial teams write their guide as a linear document in Word, for example, and then publish it as a PDF on the intranet – a thoroughly practical and proven method.
The modern knowledge portal
Companies that have a central knowledge platform (e.g. in the form of an enterprise-wide wiki, can also manage and provide the editorial guide via this method). This approach can offer some advantages over the traditional PDF variant:
- Intelligent search function that sorts hits according to relevance, even if users don't know the appropriate term and are looking for a synonym
- A wide range of structuring and design options for the content, which provide better access to information than the very static PDF document
- Extensive comment and feedback functions that simplify collaborative work on the guide
Especially with regard to the last point, it's important to implement a sensible role and rights system in the knowledge portal. This protects against too frequent changes to the editorial guide by people from outside the field.
The Content Management System
If a CMS is used, the guide can of course also be created and managed directly in the system. One of the advantages of this is that the system's multi-format output options can be used at the click of a button, allowing the guide to be output quickly and easily in different formats. Depending on the system, some of the language rules can also be mapped directly via authoring assistance. For example, aspects such as terminology or sentence structure can be checked directly while writing.
Basically, it can be said that in addition to the quality of the content, it's essential that the editorial guide be kept as up-to-date as possible and made easily accessible to all relevant people. A guide that's difficult to find and even outdated will bring little-or-no improvement and won't meet with the approval of colleagues.
Our conclusion: A central set of rules for documentation is worthwhile.
Efficient processes, greater consistency and better results: The advantages of an editorial guide are obvious. For all this to succeed, a systematic approach and the right know-how are needed. In the stressful daily technical editorial routine, the necessary human and technical resources are not always available on call. In such a situation, targeted support from an external specialist service provider can be worthwhile.
