What is 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).
Which documents make up the technical documentation of a product?
As you may have already guessed, there is no definitive list. Technical documentation is essentially about making the product usable, so the key element of technical documentation is the user manual (or operating instructions, instruction manual, etc.). It can include every aspect of the product life cycle, but can also be divided into several documents, such as a repair manual, directions for use, a maintenance manual, and disposal instructions.
By the way, technical documentation does not have to be printed documents; the majority of manuals these days come in digital form. And technical documentation does not necessarily mean written text, either. Technical documentation also includes video tutorials, augmented-reality applications, and many other audiovisual formats.
Structure and content: what should technical documentation include?
The content of an instruction manual also depends on the product, of course. But there are some fixed constants that apply to all devices:
-
All manuals must include safety notices.
-
Technical documentation also needs a picture and/or a description of the device.
- And naturally, an explanation of the different actions the device can perform.
-
Overall, technical documentation must reflect all phases of the product life cycle, that is, from transportation to disposal, covering usage, cleaning, repair, and maintenance.
-
But this does not all have to be in one document; it can be divided between a number of documents.
-
And last but not least, the instruction manual must take into account all the target groups, such as operating staff, machine operators, and service technicians.
Which requirements must be met, and what has to be considered?
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.
What makes good technical documentation?
The first point to make is that good instructions must be comprehensible. Technical writers therefore have to look very closely at the target groups they are writing for, that is, who is going to be using their products. It goes without saying that the information contained in the documentation must be accurate. But documentation must also be complete, which means that it must disclose the full range of product functions to those using the guide.
It is also especially important to warn about all the potential hazards of using the product, because otherwise there is a risk that the company might be liable – quite apart the fact that, in a worst-case scenario, users could come to harm, or even lose their life.
From the company viewpoint, it is also important for the guidance to be finished on time (that is, ready for when the product is delivered). After all, as instruction manuals are an integral part of the product, the product cannot be marketed without the instructions. And last but not least, an instruction manual should be produced in the most efficient and cost-effective way possible.
Editorial guide, documentation guidelines, style guide?
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.
Achieving optimum text intelligibility?
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.
Who creates the technical documentation?
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.
What does a good technical writer actually do?
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.
English documentation, German technical writer - how is that possible?
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.
What is the procedure for technical documentation?
Every instruction manual starts with researching what information is available about the (future) product. Technical writing departments use of a variety of sources, such as previous models and their documentation, development documents, prototypes, interviews with product experts, and much more besides. After researching the facts, the technical writers develop an information concept to define which information will be communicated to which target group, and in how much depth. Technical writing departments often work with content management systems. In this phase, they then establish which information modules already exist, which have to be modified or created, and how the information modules are to be combined.
The actual writing only starts once all this preliminary work is completed. As soon as the texts (or content modules) are finished, they undergo an approval and release process of at least two stages. First, an editorial review is conducted, in which technical authors check the linguistic accuracy and adherence to editorial standards. After that, a product expert reviews the instructions for content accuracy as part of the technical approval. This two-stage release process is often followed by a usability test with the target group for the instruction manual. The documentation is only published and delivered once it has been fully approved and released, for example as a printed manual or as interactive user guidance on the machine display.
As well as actually creating the manual, technical writing departments have a number of multi-discipline tasks to attend to. These include, for example, establishing writing standards in a style guide, defining metadata and ontologies for describing the products and their functions, or managing and monitoring translations.
What common problems are encountered when creating technical documentation?
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.
Do you have questions about optimizing your technical documentation?
Get in touch with us!
How can I make sure that the design is user-friendly?
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.
What is meant by terminology management in technical documentation?
The task of keeping terminology updated is one that also falls to many technical writing departments. Terminology management sees to it that product designations, technical terms, and typical processes, for example, are always named consistently. This ensures that term candidates are identified, terms are standardized, and terminology is allocated and publicized. Terminology management also makes translation easier, as key concepts are defined, and can always be translated in the same way.
For more information, see the following articles:
► Terminology management – a call for clarity and comprehensibility
What are metadata in technical documentation?
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.
Want to learn more?
What is “controlled language” all about?
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.
Want to learn more?
► Less is more: controlled language for more efficient documentation
Standards and norms for technical documentation
Standards and norms play an important role in technical documentation. Firstly, there are the standards for the product itself. The documentation must take them into account, and name them explicitly. There are also some standards that apply to the directions for use and the work in technical writing departments. The center of attention here are the “User Manual Standards” DIN EN 82079-1 and ISO 20607. There are also more general standards, such as those for translation management (e.g., ISO 17100) or quality management (e.g., ISO 9001). Last but not least, many technical writing departments create their own standards, in which they record the design and formulation of the instruction manuals.
Want to learn more?
► Norms and standards for technical documentation – where to look
What is the SAFE formula for technical documentation?
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.
Want to learn more?
How can review processes in technical documentation be optimized?
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.
Why do technical writers need 3D models?
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.
How can software assist technical documentation?
Modern authoring systems support technical writing departments in all aspects of documentation. They make information available whatever the medium, making it possible to publish the same content for a wide range of communication channels (e.g., physical manual, online portal, documentation app). They automatically deliver layouts for extensive manuals at the touch of a button. They provide administrative support for the different languages and product versions. They automate processes and publish suitable guides that are target group-specific and always up to date. And they organize approval and release, so that it is always possible to ensure that users only ever receive the correct information.
You want advice about our software solutions?
Get in touch with us!
What is a component content management system?
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.
► 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?
What advantages does a CCMS provide?
Modularizing your content
Modularization is a key factor in the success of technical documentation. By modularizing content, you seek to create information modules that are stored at a central location, and can be re-used in as many contexts as possible. Manuals need less attention with modular content, as changes can be implemented simultaneously at numerous points at the touch of a button, and the cost of translation falls.
A good grip on translation
It is far easier to handle translations in an XML-based component content management system. For example, you do not have to keep translating the entire manual, just the passages that have changed, or which are not available in the relevant target language. Content can also be replaced simply and in real time, via an interface with the translators, without giving them access to your authoring system. With a component content management system, you greatly reduce the cost of your translations, while also saving time in translation management and in collaborating with translators.
Easy target format creation
XML keeps layout, content, and structure separate. Layout is generated automatically. If the appearance changes, or the content is needed in a different format, it is only the layout that is modified; the content can simply be published once again. All it takes is the touch of a button – no programming knowledge is required! With a component content management system, the layout and output of your technical documentation is child’s play. You save yourself time, money, and stress. Or to put it another way: layout and output format in technical documentation have never been easier!
Simple variant management
An XML-based component content management system breaks down your documents into numerous small text and image modules, which you can reuse in a variety of different locations across all your documentation. These modules have metadata added to them to make them easier to search for and find, are managed and modified at a central point, and are even able to suggest suitable text modules to authors as they write. You can always keep track of everything with a component content management system. Tedious manual tasks are automated and the error rate is far lower.
Save yourself time, money, and stress
A component content management system provides efficient solutions for different areas of application. Authoring processes are easily optimized, costs fall, less time is taken, and the situation is far less stressful for the technical writers. Every technical writing department can benefit from the advantages of using a content management system like this!
Reduce susceptibility to errors, improve quality
A component content management system automates and simplifies processes in your technical writing department. Your documentation to far less susceptible to errors, and at the same time, its quality is considerably improved. Are you interested in a component content management system? Then take a look at what our SCHEMA ST4 authoring system has to offer.
Why separate content, structure, and layout in technical documentation?
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.
What is SCHEMA ST4?
SCHEMA ST4 is a component content management system (CCMS), or in other words an authoring system in which content is created and maintained in modules. The modular design enables content to be combined in a flexible manner and used in many different contexts, e.g., as a master copy, a webpage, in a knowledge database, or as a mobile application. SCHEMA ST4's powerful and customizable Layout Engine automatically creates the right layout for every publication.
Technical documentation is the key area in which SCHEMA ST4 is used, but it also has many other uses, e.g., for contract administration or creating training materials. SCHEMA ST4 is used in a wide range of industries, including mechanical engineering, software development, plant technology, medical device production, and the pharmaceutical industry. It is a successful international product and the technical market leader in component content management systems.
What is Content Delivery?
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 InfoTwin, by the way.
What role does technical documentation play in software projects?
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.
What is the difference between software documentation and other manuals?
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.
► Challenges of software documentation and how to master them
Learn more from our White Papers!
