Validation and quality control
Content must be validated before delivery. This may seem obvious, but it requires the involvement of the people in charge of validation from the outset. Ideally, the validation phase takes place in parallel with the creation phase: early modifications are less costly. An enterprise content management tool such as Alfresco may seem like an attractive way to set up workflows, at least on paper. In reality, however, such a solution can be cumbersome. It is also incompatible with certain source formats based on modular, non-monolithic documents and version management software (the Componize project, however, proposes managing DITA XML projects within Alfresco). It remains imperative to set up validation stages throughout the project. Combined with a version management system, comparison tools are very useful for validating updates. For example, a “tagged” version of a DITA XML project and the current version can be exported in RTF format, then compared in a word processor. This is far less tedious than a manual comparison. Comparing information modules directly in the version management system is not sufficient, as they are merely the “building blocks” of the final document.
Creation and validation workflow
Section titled “Creation and validation workflow”A process for creating and updating technical documentation that relies solely on human memory is unreliable. A technical writer may be tired, unwell, on vacation, overwhelmed with information, or may have left the company. Communication between two people can also fail or be misunderstood. Humans have created tools to compensate for these weaknesses, although they remain creative, unlike machines.
Given this situation, we need an information management system for the evolution of documentation that is tolerant of human error. This means either:
- implementing workflows under a CMS,
- using the ticket management system utilized to handle new features of the documented product (e.g., Trac):
- creation of a ticket by a developer,
- implementation of the ticket by a technical writer,
- closure of the ticket by the ticket creator,
- publication of documentation when all critical tickets have been closed.
The main functions of a CMS are as follows:
- metadata management,
- workflows,
- traceability.
Whatever the tracking system, it must offer full visibility and traceability of changes made to technical documentation (what, who, when).
This system must be unique and exhaustive: it must centralize all requests for changes to technical documentation.
If the document is available in several languages, each ticket must be duplicated for each language or, in the case of a CMS, each language must correspond to a separate workflow.