Anyone who creates a technical product, be it in the form of hardware or software, cannot avoid creating Technical documentation. And vice versa: Anyone who has ever had to operate, repair, maintain or service technical products of a more complex nature has probably consulted a Technical Documentation.
What is Technical Documentation?
In more general terms, the Technical Documentation is a subset of the Documentation and includes all information products which describe a technical product in consideration of a certain target group.
Information products are all media that are suitable to convey information. This can be a manual in paper or as a PDF, files on a CD-Rom or for download or also videos and rather less widespread pure audio files.
Technical products include all technical products that are produced or manufactured in any way. As mentioned above, you can roughly speak of all hardware and software. But it also includes all technical products without electrical/electronic components, such as a mechanical water pump or a conventional bicycle.
The Technical Documentation is always oriented to a certain line group and would like to provide product information and instructions suitable for the respective target group, which for example instruct for repairs or operations or convey a deeper understanding of the product for its further development.
Applications of Technical Documentation
As general as the term Technical documentation is, its applications are as diverse. Technical documentation includes, among other things:
- Manuals
- Assembly instructions
- Repair instructions
- Installation instructions
- electrical, electronic, pneumatic, hydraulic circuit diagrams and circuit diagrams
- Current diagrams
- help files for software (operation) for example in the form of *.chm files
- Video tutorials or tutorials in general
- Product manuals
- Product data sheets
- Maintenance conditions and instructions
- Online-Helps
From the various terms it becomes clear that Technical documentation is always tailored to a specific group of people.
The software programmer will fall back on the internal source code and software architecture documentation while the software user will consult the online help or study the CHM file.
The vehicle mechatronics technician will refer to the repair instructions of the vehicle manufacturer when repairing the injection and the electrician of the modifications to a control cabinet will use the circuit diagram as a basis.
For this reason, when preparing the documentation, care must be taken to ensure that all relevant information is presented in an understandable and well-structured manner. The presentation and presentation of the information must be tailored to the respective application. One example of annoying and poor documentation that is often used in private life is the assembly instructions for furniture from a well-known Swedish company.
External and internal technical documentation
The technical documentation is divided into external and internal documentation.
External Technical Documentation
The external documentation is intended for all users and operators of the technical product. This documentation is intended to ensure that the product is put into operation, operated and maintained in accordance with its intended purpose, and that it is taken out of operation in accordance with its intended purpose and that it is disposed of properly. This generally includes operating manuals, assembly instructions, care and maintenance instructions, data sheets on the environmental conditions to be taken into account (temperature, humidity, EMC), online help, tutorials, operating instructions. The external technical documentation is usually created by the technical writers (technical editors) of the producing company. The languages to be used depend, among other things, on the markets to be served.
The manufacturer of technical products is obliged to provide external technical documentation due to the German Equipment and Product Safety Act. This is the only way he can ensure or assure himself that the product is used and operated as intended and that there is no danger for the user. The use of the hairdryer in the bathtub is presumably not intended operation.
Internal documentation
The internal technical documentation serves to store all information relevant to the product. This includes all specifications, calculations, specifications, design bases and assumptions, risk considerations and risk analysis (HAZOP), circuit diagrams, circuit diagrams, technical drawings, material lists, production documents, product tests, etc. The internal technical documentation covers the entire product life cycle from initial planning to proper disposal.
The well-organized archiving of internal technical documentation is of great importance for at least two reasons. On the one hand, the product manufacturer can fulfil his obligation to provide evidence to authorities, courts and central monitoring bodies (e.g. TÃœV). On the other hand, the product manufacturer needs the technical documentation out of his own interest. This is the only way for them to maintain their product and the production behind it, to develop it further, to rectify product faults and to train new employees.
Legal regulations and standards Technical documentation
Legal regulations
Since many products can pose a hazard if used incorrectly or under unacceptable conditions, technical documentation is required by many national and European laws and regulations. At the top of the list is the German Equipment and Product Safety Act (GPSG) and its EC directives. The EC directives are transposed into national law by the associated ordinances, such as the Pressure Equipment Ordinance (14th ProdSV), the Explosion Protection Ordinance/ATEX (11th ProdSV), Machinery Directive (9th ProdSV) and the Low Voltage Directive or Ordinance on Electrical Equipment (1st ProdSV), to name only a few. The respective ordinance must therefore be taken into account according to the application, whereby several ordinances can also be taken into account at the same time.
In the USA, the Consumer Product Safety Act (CPSA) must be observed.
In the event of damage caused by faulty external technical documentation, the product manufacturer shall be liable. The courts will also decide on a liability claim if there is a case of damage which can be traced back to a device fault, e.g. design fault, and which can be proven via the internal technical documentation or a missing or inadequate risk analysis.
Standards and guidelines
Further requirements for technical documentation come from many standards (DIN, EN, ISO) and directives (e.g. VDI, NAMUR) or sector-specific association guidelines (e.g. VGB, ZVEI).
Standards and directives that deal directly or exclusively with technical documentation include, among others:
-
- European Standard EN 82079-1: “Preparation of instructions for use – Structuring, content and presentation – Part 1: General principles and detailed requirements”
- VDI 4500 – “Technical Documentation” (6 sheets)
- DIN EN 61355 “Classification and designation of documents for plants, systems and equipment”
- DIN 6789:2013-10 “Systematic arrangement of documents – Protection against falsification and quality criteria for the release of digital product data”
- VGB S-831 “Provision of Technical Documentation (Technical Plant Data, Documents) for Energy Supply Units”
- ISO 15787 “Technical product documentation — Heat-treated ferrous parts — Presentation and indications”
- ISO 3098 “Technical product documentation — Lettering — Part 0: General requirements”
- ISO 10209 “Technical product documentation — Vocabulary — Part 1: Terms relating to technical drawings: general and types of drawings”
- ISO 2162 “Technical product documentation — Springs — Part 1: Simplified representation”
- ISO 5457 “Technical product documentation — Sizes and layout of drawing sheets”
Every technical writer must find out in advance which industry-specific standards and association recommendations need to be taken into account. If necessary, a client may also require compliance with certain standards and guidelines in the specifications.
Create technical documentation
Structuring of the technical documentation
In relation to the respective target group, the documentation must be comprehensible and the required contents must be quickly findable and comprehensible. This requires a good structuring of the contents of the technical documentation. Depending on the focus of the documentation, there are different requirements for the structure. A furniture assembly manual will probably essentially consist of pictures that visualize the procedure in detail. More complex technical documentation, for example for a risk or hazard analysis, will first be preceded by a definition of terms. The following elements can or should be part of a technical documentation:
- Revision/Version sheet with change history
- Table of contents
- Glossary of terms
- Scope of application/target groups
- Framework conditions/Environmental conditions
- descriptive part (the actual technical content; can also be technical drawings and plans)
- ggf. lists (parts lists, material lists)
Revision and versioning of technical documentation
Subsequent changes and updates to technical documentation must be clearly traceable. This means that changes should be marked accordingly, e.g. new content should be highlighted by a dash in the sidebar or deleted content should be formatted as strikethrough. Separate change sheets (change history) are also possible, which summarize all changes to the previous version. It does not always make sense to have a huge change history, especially when it comes to external technical documentation. In the case of instructions, such change notes can rather disrupt the reading flow and content capture. It is recommended to keep the changes at least in the internal documentation.
Each new revision/version of a document should be provided with a corresponding number or letter identification (indexing), which is incremented with each new status. In addition, the publication date should always be indicated. In this way a clear reference to the document can be established. If several employees or companies work on a document, it should at least be noted internally who made which changes and, if applicable, at whose instigation or for what reason the changes were made.
Taking into account quality assurance, e.g. ISO 9001, or traceability in court, the individual revisions/versions should also be made more or less forgery-proof (data integrity). In the good old paper world, signature sheets have often been used with counter-signatures for “Created“, “Tested” and “Released“. The corresponding paper copy was then stored securely in a company archive, for example.
Nowadays the technical documentation consists mostly only of digital products, like CAD drawings, Word files, etc. Here there are other requirements for data integrity as well as for digital signatures. The DIN 6789 informs about this.
Software for technical documentation
In many companies it will probably be customary to use Microsoft Office products, i.e. MS Word, to create the technical documentation. The often cited main reason is the good exchangeability of files when working on a document across several departments or companies. Another important reason is that most editors are fit to work with MS Word. Professional technical writers often resort to special Author Tools (Help Authoring Tools), such as the DA-HelpCreator. These are adapted to the requirements for creating online help or technical documentation. It is important to be able to work quickly, for example by offering familiar editors with distraction-free mode or special editors (e.g. Markdown editor) that support fast writing and formatting at the same time and offer auto-complete functions. The import of images and other media should be done quickly using simple drag&drop mechanisms. The most important point, however, is that you can export your technical documentation in many formats so that you can make it available in various forms:
- PDF export for download or distribution as file or for printing
- HTML export for Internet or Intranet directly to the server
- CHM file to integrate a help in a software
In addition, the technical documentation software should include good content management (CMS). This means that individual contributions can be structured well and clearly in chapters and categories, tables of contents and indexes can be generated automatically and additions can be added quickly and comprehensibly in order to do justice to the revision and versioning mentioned above.
