Creating an editorial guideline
Editorial guides are a valuable means in technical documentation. They make life easier for technical editors and contribute decisively to the quality of the documents of your software documentation or manuals because they provide the guidelines to create consistent technical documentation.
What is the aim of an editorial guide?
An editorial guide contains a great number of standards that are mandatory for the creation of documents within an editorial team. That way it helps the editors to guarantee a consistent layout and a high level of quality throughout the documents. At the same time it conveys assurance in case there are any doubts. Day-to-day questions on the document structure or on the layout no longer have to be answered tediously one-by one, as a glance into the editorial guide provides the answer. New members of staff and external service providers can be integrated in short time, as they quickly and reliably become familiar with all editorial rules.
In big documentation departments spread across several locations, the editorial guide is vital in enabling the editors to work as a team. Without an editorial guide, there would emerge a shambles of heterogeneous processes and inconsistent documents.
Depending on how well structured processes within a documentation department are, an editorial guide can be anything between a small adjustment and a radical change. In a department without any controlled processes, it will take much longer to introduce a structured way of working. However, this is where an editorial guide is most fruitful. Standardizing processes will improve results significantly.
From an economic perspective, an editorial guide seems to make sense as well. On the one hand, you do have to invest time to conceive, create and maintain the editorial guide. On the other hand, it not only improves the quality of technical documentation, but also saves costs. With mandatory rules for using terminology, the expenditure for translations can be reduced significantly.
Contents of an editorial guide
An editorial guide regulates all important aspects for the creation of technical documentation: from process organization to the details of the layout.
The content of an editorial guide could look like this:
- Processes
Through which stages will a document progress from planning to archiving? An editorial guide has to provide clear guidelines to standardize processes and reduce error- proneness. This may include standards for image editing, to ensure consistent images regarding dpi resolution or colour depth, or quality-ensuring measures, such as internal reviews to guarantee the factual correctness of the technical documentation. - Responsibilities
Who takes charge of which tasks and processes? Who is the right contact person for which issue? - Structure
How will the content of the technical documentation be structured? As an example, to ensure consistency and maximum user-friendliness, the single steps of an instruction should always be structured the same way, and links should be set according to a link concept.
Link concept - Style of writing
How do you handle abbreviations which are not widely known? How do you decide on alternative forms of spelling, for example “organize” or “organise”? Will you use British English or American English? These standards ensure the linguistic consistency of the documentation.
Copy Editing - Terminology
Which terms shall be mandatory and which terms shall be prohibited? A well-thought management of terminology contributes decisively to a consistent look and feel of the documents. In addition, clear guidelines for terms in both the source and the target language reduce translation costs. Terminology can be integrated in the editorial guide. It is also common to have an own database for terminology.
Terminology Work - Layout
What are the guidelines for typography, print space, choice of colours and graphics creation? Which corporate design regulations have to be considered?
The practical value of an editorial guide
The quality of technical documentation suffers whenever every technical editor looks for individual solutions when creating and editing documents: Processes within the department are slowed down by frictions, there is no consistency in the documents, compulsory quality standards can hardly be met. An editorial guide sets an end to this mess – quality is improved, time exposure and costs are reduced.
Naturally, to make sure the editorial guide is effective, it is necessary that the documented processes and standards are put into action. That is why you should involve all parties concerned when you create an editorial guide. Only then can you be sure that the real everyday demands are taken into account – and that all members of the technical documentation department adopt the editorial guide as a valuable asset.