One of the hardest goals to achieve within a documentation team is to standardize writing styles. In most cases, information models, style guides and editorial styles are used to structure and guide the editorial writing process. But these editorial best practices are not sufficient to provide optimal and long-lasting editorial consistency.
Because of inconsistencies, the user wastes time looking for information and does not always understand the procedure as he/she should because guides and their topics use different words to describe a same concept. Besides, in case of a badly written documentation, its translated versions may not make sense. Inconsistencies also make the reuse of content difficult and sometimes impossible. In single sourcing, one of the main rules is to have homogeneous content that can be reused for different purposes and in different contexts. Since translation and single sourcing are linked, inconsistencies can be a major issue for companies.
To achieve content harmonization, a wide range of tools has been developed that can be separated into two categories: automatic tools and manual tools.
When we think about automatic tools in technical writing, the first things that come to mind are information models such as DITA that usually works with XML editors. The DITA norm allows writers to structure, reuse and harmonize the content of large documents. But there are drawbacks. Using an XML editor with an information model can be inflexible for writers.
A style guide is the typical harmonization tool. It provides guidelines on how to write for a company. It gives information about how to write a correct title, how to structure lists, or how to use punctuation marks. Considering the accuracy and the completeness of style guides, we should expect a total harmonization of content among technical writers of a same company. Why is the result completely different?
The first reason is related to the availability and the visibility of the style guides. Not only should they be mentioned when a new writer arrives in a company, but also when the writer has been working in this company for many years and may have forgotten that such guides exist, or thinks that these guides do not change.
The second reason is related to the complexity of such guides. They can be badly structured or too hard to understand. The result is that writers are reluctant to use them.
Terminological databases can be used to provide naming guidelines, approved product names and definitions. If they are well-designed, they can be very useful for a writer who wants to know quickly which name he has to use or the meaning of a word in different contexts or different products.
A number of other ways to search for terminology have appeared in companies, such as collaborative terminological spaces.
Editors are another way to bring harmonization on the documentation. It is structured around three main themes: language editing (language issues), copy editing (company’s standards issues) and developmental editing (document structure issues).
So, to improve the consistency of technical guides, several solutions are worth considering.
First of all, companies should plan training for new employees. Even if style guides exist, they are not necessarily read by technical writers, who can have other priorities when they start their new job.
Secondly, generalizing the profession of editor can be another solution. This role could be improved if combined with other editing solutions, such as automatic software editing functionalities.
Finally, I think that the centralization of style-related resources is important. For instance, a central server could gather style guides, wikis, terminological databases, field experts, and all other guidelines that could be helpful in the harmonization of styles.
The harmonization of styles is essential in technical writing because it provides a consistency that helps users understand the company’s products. It also helps them become familiar with the guides of a company. Moreover, an homogeneous content is more likely to be reused and saves time for the writers. It also saves money, in particular when it comes to translation.