The way to information 4.0

Mr. Maier is an experienced technical writer in a medium-sized mechanical engineering company. Over the years the company and therefore also the products have been developed further: The idea "standard solutions" does not exist anymore. More complex solutions are requested, and in different variants. The company has changed to the motto "flexible but fast". In the meantime, Mr. Maier updates and creates new manuals with the help of Copy & Paste.

A further difficulty is that Mr. Maier must translate the documentation into various languages again and again because the German and English versions are no longer enough. Another problem is the different standards that must be observed depending on the country of the end user.

In the meantime, Mr. Maier looses control of the whole situation. The originals and translations are available in different formats. The translation costs are high and the conversion into digital formats is very time consuming.
Now the weekend is coming up and the sun is shining. But... one of the most important customers of the company sends a report on Friday  afternoon with some errors in the technical documentation. After a short discussion with his colleagues, Mr. Maier identifies 10 paragraphs on a total of 5 pages which should be changed. That is quickly done! The sales department has therefore assured the customer that the existing documents will be available on the company portal by Monday morning.

Mr. Maier spent the entire weekend working to correct errors in the existing documentation of one of their biggest customers. He spent hours revising the documentation using Copy & Paste.

On Monday morning Mr. Maier was still working on it and the translations were still missing! His boss was anything but enthusiastic. And that increased the frustration even more. As Mr. Maier could not find any editing software on the market that could quickly solve the management of changes, he decided to think about the way technical documentation works:

After a few attempts, one thing is certain: The principle of single-source content is inevitably combined with the generation of independent content modules that can be flexibly assembled.

The first practical problem is the amount of information contained in each module. Some very long blocks of information (e.g. some standard chapters) are completely reused and have several pages.

However, Mr. Maier notices directly that this approach cannot be implemented with the current software. To create modules in their software, he therefore decides to reduce the modules to one page. Fragments are unfortunately not possible. But: Not all modules are exactly one page long. Therefore, some pages are half empty. The layout is therefore not very reader-friendly.

Mr. Maier has created a folder structure. Now he wants to define metadata. These are properties that defines the modules. He thinks about it. He gives clear names to the modules, the folders also get names. The names go from the product line to the item number. Thanks to these names, also called metadata, he can now easily compile his documentation.

But he wants to go away from the old system and automate the documentation. That's why he has started to search for different systems and he already has several offers. But most of the software vendors have not given a real final price. They point out that a use case is necessary to define the requirements.

Mr. Maier tries to answer:

He sends his answers to all software vendors. One software vendor answers promptly and offers a free trial.
Mr. Maier is pleased. He answers and asks for a test version. While he sets up the test version on his computer, Mr. Maier gets another e-mail with further questions and the suggestion of a demo.

In the meanwhile Mr. Maier has set the test system up. The system is connected to MS Word and has macros that automatically create the document in MS Word. He imports his nodes. Now he wants to set up metadata and taxonomies. There is no real function for this. He can do it using only the folder structure and file names.
With the help of templates, he can now reuse his nodes and MS Word automatically creates the document, but somehow it takes a lot of time.

And now he is importing the translations. The system works pretty good. But you have to revise the translations afterwards in MS Word, because every language has a different length.
For the moment he has an example layout for the CCMS publication. But, he is considering whether the documents can be created in other layouts as well. That would be great of course! He contacts the software provider. The answer comes immediately:

The test system works. But Mr. Maier is thinking: If I import my documents into a CCMS, not only in a clear structure is necessary, but I must write according to writing rules. Did the providers said something about authoring assistance?

Rules are everything!
Mr. Maier would like to concentrate on grammatical and stylistic rules first. After a long search he finds the rules of Simplified Technical English and the guideline "Rule-based writing" of the German association of technical communication TEKOM. He buys both editions and reads them.

He takes a translated text and tries to rewrite it according to the rules. It takes quite a lot of time, but the before and after effect is clearly visible:

In the meantime, he now wants to define some basic rules.

The titles must be short, explanatory and clearly structured.
Verbal titles are easy to understand.

Example:

There are different approaches in the TEKOM guideline. It is important to decide on one method and to apply it consistently. Mr. Maier appreciates this approach and combines it with STE.

Unnecessary repetitions must be avoided in the title structure. Otherwise the titles are not reader-friendly and the structure is not always clear.

Well-structured and organized titles help the operator to find his way through the manual. Do not forget this rule. The titles define the basic structure of a document.

In contrast to books, you should not use pronouns in technical communication. Pronouns can lead to misunderstandings.

Technical communicators often leave out prepositions. Then writing is faster and space is saved. But then the reader has no references in the text. This can be misleading.

Passive sentences leave the doubt about who must do something. Passive sentences should be avoided in technical writing. The operator must know what he must do. We must exclude interpretation possibilities!

But numbered lists are not really grammar. As a next step, Mr. Maier would like to analyse the structure and the layout.

Short sentences
Nested sentences are usually incomprehensible. The reader must read the sentence several times. Especially in a descriptive text the technical communicator should pay attention to the text length. As a thumb rule you could set a maximum of 20-25 words / sentence.

The structure and sequence of the sentences must be logical and correspond to the operation sequence.

Lists:

Both numbered and bullet point lists must be uniform:
•    Define if to start with capital letters or not.
•    Define the punctuation.
•    Do not interrupt sentences.

In our example we have a complete introductory sentence. Do not use articles to avoid accusative problems during translation. Start with a capital letter in the list. Omit commas and add a full stop at the end the list.

These rules are only suggestions. The technical writer must define clear writing rule to guarantee consistent texts.

Style:
And t you can also save on translation costs:

Now Mr. Maier would like to define the technical terms, as in STE.
In our next blog, Mr. Maier is looking for a system that combines terminology and technical writing and different layouts and formats in one CCMS.