Last update at 07 · 03 · by milo‧‧‧ One of 6
Language used in documentation has a major impact on the readability of the content and also on the usability of the product being described. In order to produce good content requires special strategies for establishing and maintaining high quality. Like anything else, quality has its price, but the cost of well-written documentation is measurable, provided that quality criteria are clearly defined.
When you buy a digital camera, you don't just walk into the nearest store and hand over a random sum of money without being sure that the camera you pick out meets your specific needs. In some cases, we are prepared to compromise - if the price is right. Let's say you see a camera that offers slightly fewer features than the model you originally had in mind, but is price-wise still a great offer.
You decide to compromise and buy the cheaper model. Later, you discover that you need exactly the features you were willing to forgo and kick yourself for not having paid that bit more or thinking through the potential uses of the camera. Despite your disappointment in your choice, you will not blame your purchase for your false economy (provided that the available features meet generally acceptable level of quality). After all, you knew exactly what you were getting when you bought it.
Language in documentation
Linguistic quality of content
In technical documentation, language also displays specific features that can influence the linguistic quality of content and extend or restrict documentation use. However, language is seldom quantified in the same way as the features and performance of a digital camera. Customers pay for the finished result, but are not always aware of the various levels of language control that are necessary or can be optionally performed to create high-quality multipurpose content.
Language control is important in all writing. However, the specific conventions which apply to writing a press release are not relevant to documenting a technical procedure, and so on. Compliance with specific conventions is needed for different documentation projects (customer-specific, industry-specific, product-specific, user-specific) or types of documentation (manual, online help, Web site, brochure).
Beyond standard writing conventions
There is no objective scale of one to five that defines whether linguistic quality is poor, mediocre, acceptable, good or outstanding. To assess language, it is necessary to first define quality criteria. The most basic elements are language include spelling, grammar, punctuation, formatting, structure, and style. We generally accept that good content contains no spelling errors and obeys best writing practices. But the increasing globalization, automation, and scope of documentation production place greater demands on the end result, for example:
- Appropriate language
- Consistent terminology
Without careful planning, organization, and coordination, even the most experienced writers and translators struggle to meet all quality criteria. Strategic quality management of language-related aspects is essential.
Pitfalls of shortcuts
Pressure to deliver quickly and provide documentation at competitive prices can lead to quality-assurance steps being neglected. For example, a customer requests an update of a document for a software documentation project. The technical writer who originally wrote the document is unavailable. To avoid turning down the customer, the document is assigned to a writer who is not familiar with the project. The writer is told to deliver the updated version the following day. Feeling slightly unprepared, but not wanting to appear incompetent, the technical writer tackles the task and sends the updated document to the customer without consulting any other colleagues. Unfortunately, the writer is not aware that a series of related documents exist, that screen shots of the software interface were provided with the document, and that the original creator of the document has saved a project-specific style guide on the local drive of a notebook.
The result is 'not bad'; the updated document conforms to general spelling and grammatical conventions, but contains inconsistencies with other project-related documentation and the product itself, such as:
- User-interface terms
- Use of abbreviations
- Use of bulleted lists
- Heading conventions
Process-oriented language control
If a form of quality management involving process-oriented language control had been implemented, the writer could have avoided these inconsistencies.
One purpose of quality management is to establish preventative measures. For example, the task of updating documentation ismade easier if writers have all relevant information at their disposal, such as:
- Project-specific guidelines
- Terminology lists
- Screen shots (for software documentation)
- Other relevant product information
If this information is not available, it is impossible to perform effective internal quality checks later, and the documentation may not meet all the customer's requirements.
Quality steps must be integrated in the whole documentation creation process and not at the very end of a project. This not only improves the quality of the end result, but can also save time and the costs of content development, documentation production, localization, and translation.
Integrated quality assurance
The technical writer in the example worked on a document update in isolation. In projects with integrated quality assurance, documentation is not released without the approval of a second project member. this not only produces quality, but also ensures that more than one person in familiar with content and can cover for absent colleagues. Quality assurance begins with the writer and the question: Is all information available? The second quality step is performed by another technical writer or a copy editor. However, step one and step two are not performed in isolation; feedback flows between the two steps and is documented for future reference.
Ideally, one person is responsible for actively implementing and overseeing compliance with the quality-assurance process. The tasks involved in quality management are:
- Defining language criteria
- Assessing the required level of quality assurance
- Enforcing a policy of language control (including mentoring)
- Gathering and distributing information
- Defining process steps
- Promoting knowledge transfer among team members
- Managing an effective archiving system (content management)
The complexity of language-control issues in documentation is often underestimated. Language requirements are insufficiently defined and tasks are performed in isolation. Content often fails to undergo quality-assurance processes due to a lack of quality management. Despite the number of documentation tools available on the market, technical writers, copy editors, translators, and other documentation specialists are ultimately responsible for the quality of language produced. Integrating these specialists' work in a comprehensive quality-assurance process can significantly improve documentation quality, streamline documentation processes and lead to greater customer satisfaction. After all, if customers know exactly what they are getting, they might be willing to pay that bit more.