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

Technical writers and translators: a win-win relationship?

Fanny Bellaïche, Juliette Massardier and Marielle Morizot

August 2014

Abstract

Traditionally, technical communication leverages both technical writing and translation expertise. As both professions share some common skills and objectives, the activities of technical writers and translators are sometimes mixed up. However, they remain two clearly separated occupations and thus complement each other. Based on our working and academic experience as technical writers and translators, we are particularly aware of the importance of a balanced collaboration to align the documentation process with the requirements of today’s industry practice. Current research on the relationship between technical writers and translators mainly focuses on the study of their competences . This paper intends to go beyond the mere analysis of competences and to explore some best practices in order to bridge the gap between both professions: more specifically, to which extent can we consider the translator as a useful resource to improve the writing process? Firstly, we examine why technical writers and translators often collaborate to deliver efficient documentation in their respective fields of expertise. Secondly, we try to understand how technical writers and translators develop shared tools, such as style guides, in order to take advantage of each other’s work. Finally, we show that enhancing this relationship is not the only way to deliver professional  documentation.

Read the full article (PDF): Technical writers and translators: a win-win relationship?

The stakes of collaborative writing

Simon Saint-Georges, Chloé Jaouen

July 2013

Abstract

The arrival of Web 2.0 has changed the ways of working, especially for writers. A wide range of tools now exists, enabling different people to participate in the writing of one single document and introducing new methods of work within teams. These new work methods rely on tools that are constantly evolving. While some companies remain skeptical, others are already embracing these new practices.
Either way, our position of apprentice makes us ideal observers concerning the choices made by our companies and the difficulties that the adoption of these new work methods raises. Such a change can be a real challenge, and selecting the right options to fit one particular situation can be a difficult task.
We will first present the results of our research on the current state of the art in collaborative writing and how and why companies tend to use more and more collaborative writing methods.
We will then explain the situation in the two companies that we work for, Atlas Copco (industrial tooling and equipment) and CNES (Centre National d’Etudes Spatiales, the French space agency), two companies which are heading in opposite directions in terms of collaborative writing. We will observe the practices, tools, processes and work dynamics involved in writing for both companies.
Finally, based on what we found and observed in the first two parts, we will compare theory and reality concerning collaborative writing in companies.

Read the full article (PDF): The stakes of collaborative writing

Moving to structured documentation: migration stakes

Sara Chaoui, Margaux Chatelain, Julie Dezalay and Justine Gaillard

July 2013

Abstract

Technical documentation can be written and delivered in two ways: it can be  structured and will follow an XML information model; or it can be unstructured and cannot be validated against a model. Nowadays, companies tend to migrate their documentation from unstructured to structured content.
This article focuses on the stakes of moving from unstructured to structured content and explains the key aspects of this process. First, we will identify the reasons of the migration by studying different approaches in several companies. Secondly, the results and/or expected benefits of the migration will be discussed. Interviews of technical writers, documentation managers, and information architects will help us define what the advantages of structured documentation are. We will focus on the added value for the technical writer and for the documentation reader. Moreover, we will try to understand what the company gains from the migration. To conclude, we will draw five guidelines for a successful migration. Moving from unstructured to structured content is a challenging process and the best based on experience and know-how.

Read the full article (PDF): Moving to structured documentation: migration stakes

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