- Technical Documentation
Put very simply, technical documentation is the part of product communication that explains the product and makes it possible for users to actually use it. It is therefore not about advertising and press releases, but “hard” facts. Technical documentation can look very different, of course, depending on the product. When printed out, the instructions for an Airbus will occupy entire rooms; the instructions for the new iPhone, on the other hand, are contained in a tiny leaflet (with further information on the device itself in digital form).
In addition to product communication for customers, technical documentation can also be aimed at in-house employees (internal technical documentation) in the form of work instructions, for example. Here too, the purpose is to communicate how to make products usable, but it is often also about documenting certain operations (in a maintenance schedule to be completed by service employees, for example).
The content of an instruction manual also depends on the product, of course. But there are some fixed constants that apply to all devices:
If you know a lot about manufacturing companies, you will be aware that technical documentation has a lot to do with standards and directives. For one thing, the documentation has to take into account all the standards that apply to your industry and your product (like the Machinery Directive 2006/42/EC). There are also a large number of standards concerning processes, quality management (e.g., DIN 9001), and text layout (e.g., DIN 1450) in general.
Finally, there are also some standards specifically for user manuals and other technical documents (e.g., DIN 82079-1). The whole thing becomes even more complicated when products are exported, as different target markets naturally have their own different standards. Added to this are standards for translating the instructions. Last but not least, most companies also have their own, internal norms and standards for managing the quality of their guides and instructions. In total, a significant number of standards.
The editorial guide is a key component of linguistic quality in technical writing. Unlike the CI manuals used for marketing content, its primary concern is not the regulation of design and layout, but of the linguistic style of the product manuals. The main aims for the documentation are for texts to be consistent, translate well, and be easy to understand.
Optimum intelligibility can only be achieved in technical documentation if you have a clear picture of the target group you are writing for. Instructions should not only be precisely formulated, but they should also be expressed in language that is as simple as possible. Also applicable here is the principle of minimalism, of not burdening users with unnecessary details, so that they can quickly find the information they are looking for.
Technical documentation is created by technical writers in technical writing departments.
Many other people are also involved in producing the documents. Developers or others with the relevant product expertise provide the technical input. Terminology experts make sure that terms are used consistently. Engineering draftsmen and draftswomen create the graphics, both during development and while the documentation is being produced. In exporting companies, translators make sure that the documentation is translated into the languages spoken by the customers. New occupational fields are also constantly emerging in technical writing, such as content architecture, video editing, chatbot modeling, or scrum master in agile documentation processes.
Technical writers do far more than just write instructions and manuals; they also cover aspects such as researching, text concept, and content management. In addition to this, there are a number of organizational tasks, such as printing or translation management. Technical writers frequently also take on additional tasks that have little to do with writing, such as terminology management or managing spare parts catalogs.
It is normal in many companies to have English documentation and a German technical writer. And even if this situation is not ideal, measures can be taken to ensure that foreign language authoring can work. It is important to have a well thought out editorial guide, professional translation management, and above all, a thorough proofreading phase. Automated test software and trained proofreaders should both be involved in this review.
One of the main problems in many technical writing departments is time pressure. Researching, writing, reviewing, translation, and production all take time; and in some extreme cases, even longer than manufacturing a special-purpose machine. Many technical writing departments therefore rely on powerful and efficient software solutions, such as content management systems, that can speed up the individual process steps, yet be relied on to provide the right information.
Another problem.is dealing with variants. The product portfolio of modern manufacturers is often highly customized: customers can pick almost any product they like. Technical writing departments must also be able to reflect this individuality, so that customers are only ever given explanations for the functionality of their particular product version. Other document variants are produced for different target groups (basic and professional versions), and for different language variants and regional distinctions (translations, versions for the UK and US market). A powerful and efficient content management system is also helpful for keeping track of these problems.
The days are long gone when the only product documentation you got was a slender information leaflet. Now users expect to have the right documentation at the right time, in the medium and scope that best meets their needs. Modern documentation is therefore not just digital and interactive. It helps product users to satisfy their need for information quickly and vividly, e.g., with 3D animations or product videos.
Usability tests are normally run to establish what type of information is most suitable for the target group and the usage situation. This involves representative test groups working on product-related tasks, or answering questions about the products. It is then possible to identify how well the instructions work.
Metadata are the key to automation in technical documentation. They are used to establish how a content module can be used later on: Which product parts does it describe? In which phase of the product life cycle is it relevant? What is the intended target group? Metadata can be individually specified for different companies, products, applications, and usage scenarios. They can also have mutual dependencies, so the metadata concept for a content pool has to be thought through very carefully.
Controlled language probably sounds intimidating at first, but it does make everyday working easier. What is actually controlled here is not the technical writer, but the language. This should be as consistent and comprehensible as possible. It is then no longer necessary to make so many decisions when writing; and instruction manuals can be produced more quickly and in a consistently high quality. Software systems for controlled language check the texts while they are being written in the content management system, suggest formulations, and point out problem areas.
One of the most important functions of user manuals is preventing property damage and personal injury. Technical writing departments have therefore developed their own standards for safety sections and warning notices. The most important principle is the so-called SAFE formula, which describes how the hazard level is indicated, and how to combine a description of the hazard with measures to prevent the hazard.
Quality is important in technical documentation and accordingly makes quite specific demands of the review process. Different roles must be included in the proofreading phase. Not only must the manual be technically correct, but it must also meet linguistic requirements, and have the right layout and usability. The review is therefore usually organized in several cycles. Often a quality objective is also defined for the review, and put into practice using the four eyes principle, for example. Checklists give a clearer picture of the tasks that have to be completed in every review.
3D models have many advantages for technical writers. They're clearer than text or simple illustrations. The user can select the viewing angle, and zoom into an object or gradually disassemble it into its constituent parts. What's more, 3D models can be used as a navigation tool: simply clicking on the part opens the corresponding description page. Last but not least, 3D models are a good starting point for animations in manuals. It's clear to see that 3D models can play an important role in documentation.
Component content management systems such as SCHEMA ST4 manage content, whatever the layout. Content is classified semantically and where applicable, managed according to the variant. This means that technical writing departments can re-use a lot of their content, and be extremely flexible about issuing content in different media. Component content management systems are worthwhile for most technical writing departments that have to create vast quantities of documents in many variants. They are also highly beneficial for technical writers working alone.
Want to find out more? Click here for more information on the subject:
Does Your Technical Writing Department Need a Component Content Management System?
The major advantages of a component content management system in technical writing
Is working with a Component Content Management System really easier?
The process of separating content, structure, and layout initially seems to be a backward step. After all, WYSIWYG has been the default approach to document production for many years. If you want to use large quantities of documents efficiently, then separating layout, structure, and content is the method of choice. You gain reusability and media neutrality. The content units can be re-used in totally different contexts and laid out for every possible (print and online) format. The same text passages can then emerge in very different contexts - in a printed manual or as part of an interactive Help function on the machine display.
Content delivery is more than just a slogan. At its heart is the idea that users can access what is for them the appropriate information, in the appropriate form, on every platform, at any time. This requires a sophisticated target group and rights concept, metadata to control the content and, of course, a server to distribute the content. We recommend the Quanos InfoCube, by the way.
The technical writing department plays a number of roles in software projects. The first of these being that it is responsible for producing the instruction manuals and context-sensitive Help texts. But it is also often the first body that analyzes the software from the customer viewpoint, and therefore identifies usability errors on the software interface, or convoluted means of operation. The technical writing department also ensures terminological consistency, so that functions and interface elements in the software have the same name in every location.
Software documentation has some distinctive aspects, compared to other product manuals. The documented product is not tangible, but is often highly complex. It deals with a variety of different topics and target groups, and is often subject to frequent changes. Not only that, but the processes used in software development (such as agile methods) are not always easy for technical writers to engage with.