Laure-Amélie Le Stang, Camille Riche, Alizée Rodriguez
This research article aims at studying how to create different levels of usage using structured documentation, once user profiles have been defined. From the review of different articles written by technical writing experts, to the analysis of various use cases, we will examine several solutions to document functionalities or products for a complex and diversified audience. In the first part of our paper, we will analyze existing techniques experienced in our companies, such as single sourcing and filtering metadata. In the second part, we will focus on a specific use case, and present the challenge of a company which is trying to optimize costs, improve the quality of its documentation, and at the same time, address different user expectations. In conclusion, we will see there is not one perfect solution, but some useful techniques, each adapted to a particular issue technical writers must identify before selecting the right one to fix it.
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.
Sara Chaoui, Margaux Chatelain, Julie Dezalay and Justine Gaillard
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.