10 FAQ on technical documentation

Do you have little experience with creating technical documentation or having technical documentation created? Below you will find answers to the most frequently asked questions that arise in this context.

Which documents are actually covered by the term "technical documentation"?

The term "technical documentation" generally covers all documents that are required to fully describe a product or system and its use – both from a technical and from an operational perspective.

Technical documentation can be required both internally within the manufacturing company and externally for partners, customers, or authorities.

When used internally, technical documentation ensures that a product can be successfully developed further and that the necessary knowledge and specifications are not forgotten or lost when employees leave the company.
In the case of external use, the technical documentation ensures that a product can be used safely and to its full extent by its users. There may also be certain legal or contractual requirements that require certain information or data to be recorded in writing.

In the narrower sense, the term "technical documentation" includes in particular: user manuals, online help systems, assembly instructions, installation instructions, operating instructions, maintenance instructions, repair instructions, troubleshooting guides, source code documentation, API documentation (interface descriptions), data sheets, spare parts catalogs, packaging instructions, transport instructions, release notes, and comparable documents.

What requirements must technical documentation fulfill?

Ultimately, all essential requirements for external technical documentation are aimed at enabling the users of a product to use the product fully and safely. To ensure this, numerous requirements have been defined in various standards and directives. In some cases, there are also statutory requirements.

Further requirements arise from the creation and maintenance process of technical documentation over its entire life cycle.

See also the more detailed information on this topic at: Requirements for technical documentation.

Does technical documentation have to be printed or is online documentation also sufficient?

Previously, with the exception of software documentation, technical documentation in Europe had to be supplied in printed form on paper together with the product in physical form. Purely electronic documentation was not sufficient.

This debate has now moved on and the authorities are slowly recognizing the changing times. The above statement therefore no longer applies without restriction. In most cases, at least, not all information has to be supplied in printed form.

However, in order to be able to answer the question in detail, it is necessary to take a closer look at the individual case and, if necessary, seek legal advice.

What are the special features of software documentation?

Unlike technical documentation in mechanical and plant engineering, software documentation has been strongly influenced by US companies. Aspects of product safety often are not as crucial than in hardware documentation, because in most cases the operation of software does not pose any immediate health or life-threatening hazards. Questions relating to safety instructions and the conformity of technical documentation with standards therefore only play a minor role in software documentation.

Naturally, the topic of online documentation is particularly important in the area of software documentation. It is state of the art for software today. As users use and read online documentation differently to printed operating instructions, the structural and didactic requirements are also different.

In addition, the update cycles for software are usually much shorter than for a physical product (hardware). It is not unusual for software to have a new release every few weeks. Accordingly, the technical documentation for software also needs to be updated more frequently than the technical documentation for hardware. On the part of the creation tools and processes, this requires a higher degree of automation in order to be able to work economically.

Who creates technical documentation?

In most cases, it is advisable to have experienced technical writers create the documentation. Today, "technical documentation" is a multi-year course of study at a university and requires special skills if everything is to appear as simple and self-evident as possible in the end.

In practice, however, things often look different: In reality, a large proportion of technical documentation is created by people who are neither really qualified to do it, nor enjoy doing it. Writing manuals often remains an unloved task for developers or product managers. Although this has the advantage of great expertise in the technical domain of the product, it often ends up being a problem: these authors tend to assume too much prior knowledge on the part of the reader and find it difficult to put themselves in the shoes of outsiders without this prior knowledge.

Occasionally, the creation of technical documentation is also delegated to working students or office staff. This may seem cost-effective at first glance, but will rarely convince your customers and ultimately is therefore often the most expensive solution.

Where can I find a service provider to create technical documentation?

If you are not in the fortunate position of being able to fall back on a personal recommendation, in addition to researching on the web the website of the industry association tekom is a particularly good starting point for your search. On the tekom website there is, among other things, a Database of service providers who specialize in technical documentation.

How long does it take to create technical documentation?

The amount of time you need to allow for creating technical documentation depends heavily on the product to be described and how much prior knowledge its users have. The creation of illustrations can also be a significant factor: If you can work with screenshots, photos, or existing CAD data, it will be much quicker than if lots of elaborate graphics have to be designed from scratch. As screenshots are usually the easiest type of illustration to create, the creation time for software documentation is usually significantly less than for hardware documentation. When creating new technical documentation, the total time required, including concept and layout development, is somewhere between 1.5 and 3 hours per page.

Important: Good technical documentation is as short as possible, because then it costs your customers little time to read and makes the operation of your product appear simple. However, presenting information concisely is very demanding. In practice, this means that it takes longer to present information compactly on one page than to quickly and thoughtlessly fill two or three pages with it.

Therefore, never measure productivity by pages or amount of text. Less is often more! Also, never pay a technical writer by the number of pages written. This penalizes good work.

What does it cost to create technical documentation?

Similar to the time required, the costs for creating technical documentation also depend heavily on the product in question and its users. If you multiply the average time requirement of 1.5 to 3 hours per page by your internal hourly rate or by the hourly rate of a service provider and this in turn by the estimated number of pages required, you will get a rough estimate.

By the way: If you are employed by a company, you cannot simply divide your salary by the number of hours you work to determine your own fictitious hourly rate. You must also take into account the costs of your workplace (building, furniture, computer, software, heating, electricity, insurance, etc.). You also have to take into account the costs and time for administrative activities, meetings, training and sick leave, which means that your internal hourly rate is significantly higher. You may be able to obtain more precise figures from your HR department or from Controlling.

If the costs for creating comprehensive technical documentation seem high to you, compare these costs with the costs that flow into the development of your product. In most cases, this will quickly put things into perspective. Ultimately, the development of the documentation is also part of the development of your product.

Which software programs are best used to create technical documentation?

In fact, the majority of technical documentation is still created using Microsoft Word. The main reason for this is simply that the program is already in use in the company anyway. However, this decision rarely makes economic sense. You are missing out on many extremely time-saving opportunities offered by programs and authoring systems that specialize in creating technical documentation:

Separation of layout and content: Authors can concentrate fully on the content. The software takes care of the layout. In addition, the layout can be changed at any time without having to touch and reformat the texts.
Multiple use of content: Once you have created content modules, you can reuse them as often as you like. For example, you can create legal notices or frequently required warnings just once. If you need to change the text later, you can change it in a central location. All documents that you generate from this point onwards will then automatically receive the new version of the content module in all places.
Single source publishing: You can generate documentation in different output formats from the same source at the touch of a button: for example, both as a printable manual in PDF format and as HTML-based online documentation. If required, you can also output technical documentation from the same source in different versions, for example as the documentation for a standard version of a product and as the documentation for a professional version of the same product. Or for different target groups or sectors. Or as an OEM for different customers in a completely different design.
Link management: You can create cross-references conveniently using drag and drop. If you later change, move, or delete content, the authoring system automatically adjusts all cross-references in the background and ensures that there are no breaks.
Version management: You can access earlier versions of a product's technical documentation at any time. A database seamlessly documents which person made which change to the documentation at which point in time.
Workflows: If you work in larger teams, content can go through a step-by-step process, from creation and corrections to approval, translation, and publication.
Review process: People who proofread a text can leave comments in the system. Other people and the authors can see these comments directly in the right place, discuss them and accept or reject them.
Translation management: If technical documentation needs to be translated into one or more foreign languages, you can send translation packages to the translators directly from the authoring system. After translation, you can return the translation packages at the touch of a button. If documentation does not have to be completely retranslated after an update, the system automatically extracts only the changed sections, which saves translation costs.
Automation: At the touch of a button, you can produce all of the needed documents in all variants and languages with a single command.

Authoring systems for creating technical documentation are available in all sizes and price ranges, both as desktop applications and as software as a service (SAS). For creating online documentation, there are also numerous open source solutions. See also: Help authoring tools and authoring systems for technical documentation.

How should I plan the creation of technical documentation and where do I start?

Regardless of whether you create technical documentation yourself or have it created by a service provider, you should proceed in the following steps:

Definition of the target group: Determine internally for whom exactly you are creating the technical documentation. Base all decisions concerning the technical documentation on this target group (and not on your own preferences).
Analysis of the knowledge gaps: Based on the previously defined target group, determine the delta between what these people already know and what they need to know to use the product.
Draft of the structure: Define the required information modules (so-called "topics") and arrange these topics in a didactically meaningful order and a clear, flat structure.
Editing: Write the previously defined topics. The draft structure is not set in stone, but provides a guideline. You will always find that information is still missing or that a different structure is more suitable in detail. Nevertheless, it is important to start with an initial draft structure and not to write completely out of the blue. (This is also possible, but ALWAYS costs more time overall).
Tip: Write introductory, overview-type information as late as possible, even if this information is typically at the beginning of the document! Although this content is supposedly "simple", it requires the best overview of the product and is the most challenging to prepare didactically. When writing, it is often best to start with referential information, such as parameter descriptions and technical data. Then move on to writing step-by-step instructions and only at the very end write content that conveys the mental model of the product and helps users to understand the logic of the product (concepts).
Review: A second person should always proofread every text – both from a technical and from and editorial point of view. Even with the greatest care, EVERY author is blind to many of their own mistakes!
Tip: If absolutely no second person is available, it can help to have your text read aloud by a software program. You will be amazed at how many mistakes you hear that you don't even see in the written text. A printout on paper can also help you spot errors that you are simply blind to on the screen.
Corrections: When incorporating the changes and corrections resulting from the review, special care is required to avoid making new mistakes in the revised items that no one will notice. Usually, no further corrections are made afterwards.
Layout check and production: Once all texts and other content have reached the final stage, you should look at the final layout of the document again. You can then publish the documentation in the source language.
Translation: The final step may be to translate the technical documentation into other languages. In practice, the time when the product is still in a final internal test phase is often used for this step.

Tip: Not all chapters in technical documentation are equally important. There are almost always a few functions in a product that cause users particularly frequent problems. Accordingly, the corresponding topics of the documentation will be read much more often than other topics. Spend a lot of time and care on those topics that:

are read particularly often
determine success or failure
are read at the very beginning of a product's use, while you still have the chance to convince users of your product and the value of its technical documentation

For all other topics, you can slightly reduce the time and effort required to create them. In this way, you can make the most effective use of a limited budget in terms of time and costs!