Requirements for technical documentation
Technical documentation must enable the users of a product to
- successfully assemble, install and commission the product
- use the product safely and to its full extent
- maintain and repair the product so that its functionality is permanently ensured
- decommission and dispose of the product (including disassembly if necessary)
- transport the product if necessary
Ultimately, all requirements boil down to one crucial question: Does the documentation help users to use the product in the best possible way, or does the documentation leave users "out in the cold" and fail to protect them from avoidable dangers?
Legal requirements for technical documentation
Legal requirements for technical documentation can vary depending on the country and area of application of the product. Observe the specific regulations of all countries in which you will place the product on the market and which apply at the time the product is placed on the market.
There are specific requirements in the European Union, which are primarily determined by the CE marking and the product safety directives.
Information on the most important standards and directives can be found under Top 10 standards and directives for creating technical documentation (translated from German live via Google Translate).
Didactic requirements for technical documentation
Good technical documentation does not provide as much information as possible, but the right information. And it does so in a "foolproof" way, but without making users feel like a fool.
The challenges are to:
- provide the required information as accurately as possible, tailored to the users of the product, but not more information
- design the information in such a way that it cannot be misunderstood or misinterpreted
- present the information in such a way that it can be understood with minimal effort and users find the product intuitive and easy to use
- present the information in such a way that it can be absorbed in a minimum of time
- present the information in such a way that it can be retained in the best possible way
- make the information easily accessible
- guide users quickly to success, motivate them, keep them in a positive mood, and excite them about the product
Organizational and structural requirements for technical documentation
The most important organizational requirement for technical documentation is that it becomes available at the same time as the product. Otherwise, the market launch will be delayed simply because the technical documentation is missing. Simultaneous completion is not always easy to achieve, as many products change literally up to the last minute before market launch. This is often the case with software and software-controlled products in particular. The technical documentation must then follow these changes simultaneously, maybe even in multiple languages.
It is important that technical documentation is as modular as possible (building block system):
- A modular structure enables users to read technical documentation in parts and still understand the individual isolated parts. (Or do you know any users who read a complete manual from cover to cover?)
- As a manufacturer, a modular structure enables you to reuse individual information modules multiple times if necessary – either in several places within the same document or in different documents. There are often large overlaps between related products. If the content of the technical documentation has a modular structure, you only have to create the identical content once and, more importantly, only have to maintain and maybe translate it centrally in one place (assuming the use of a suitable authoring systems).
The basis for creating technical documentation should be a concept that defines the information types used in the technical documentation and their structure. If several technical writers are involved in creating the documentation, a common concept with a common writing style guide ensures that in the end everything appears to be from a single source and that readers can find their way around all parts of the documentation at any time.
Special requirements for software documentation
Hard to believe, but a bitter reality: There are still traditional, book-like manuals for many software programs - whether printed on paper or electronically as PDF files. However, things can be so much better. Context-sensitive online help has been state of the art since the end of the last millennium. Online documentation can guide users to the information relevant to them much more quickly and accurately than a traditional manual ever could. This does not mean that traditional, printable software manuals should no longer exist. With a suitable authoring system, it is quite possible to generate both from the same text source without any significant additional effort: Online documentation immediately available with the product at the touch of a button on the screen AND a printable manual for reading longer sections offline.
From an organizational point of view, software documentation often poses a particular challenge in that changes to the product are usually more frequent than to a physical device (hardware). Accordingly, software documentation also typically needs to be updated frequently. The creation and publication process needs to support this.