Tools and methods to achieve consistency in technical documentation

Fanny Bischoff, Emeline Picart, Carlie Rames

July 2014

Abstract

In technical documentation, content must be clear and consistent and visual layout as a whole must be uniform. Ensuring these principles makes it easier for the user to understand documentation and reinforces branding. This seems simple however achieving consistency requires a great deal of organization and effort from technical writers. The aim of this article is to present and defend various solutions for achieving consistency and improving user experience, through observations made in three different professional contexts: two computer software companies and one software and hardware company.
In the first part, we will define some of the key elements that impact consistency: grammar rules, methods to address users and acute text architecture and present concrete tools and methods to improve consistency and their constraints. In the second part, we will present the most important aspect to take into account in order to find the best balance across methodologies to achieve consistency in technical documentation.

Read the full article (PDF): Tools and methods to achieve consistency in technical documentation

Implementation and benefits of minimalism in technical writing

Aurélien Delattre, Yann-Olivier Grohan

July 2013

Abstract

This article explains how minimalism can improve the quality and effectiveness of technical documentation. In the first part, we will define minimalism and its main principles, such as action-oriented approach and topic-based authoring. In the second part, we will conduct a comparative analysis based on the technical documentation of two working environments: Societe Générale Corporate Investment Banking and HR Access. We will analyse how  minimalism impacts the effectiveness and searchability of the documentation. These different minimalism approaches depend on quality criteria adopted for documentation. As a consequence, the decision to apply minimalism or not depends on the context (targeted-audience, access to users feedback). To conclude, we will identify some of the best practices to implement minimalism in any  documentation department.

Read the full article (PDF): Implementation and benefits of minimalism in technical writing

Challenges of harmonizing technical writing styles

Amélie Allard, Tyffanie Boniou, Camille Hubert, and Nicolas Philippe

July 2013

Abstract

Harmonizing technical documentation content is one of the main goals of technical writers. However, harmonizing technical writing styles is one of the most difficult tasks to implement in companies. 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. Indeed, in a company, it is common to find inconsistencies within a document and across several documents making up a document set. This article deals with both cases.

First, we will present the current state of the art in this domain. Then, we will focus on the writing tools and guidelines used by four software editors: Dassault Systèmes (3D Software), HR Access (Human Resources), KXEN (Knowledge Extraction Engine) and SAP (Systems, Application and Products for data processing). In the third part of the article, we will analyze the strengths and weaknesses of the tools and guidelines previously presented. Finally, we will propose solutions to improve the job of technical writers and editors in their challenge to implement a unified writing style.

Read the full article (PDF): Challenges of harmonizing technical writing styles