Modularisation for beginners

Getting modularisation right is a critical success factor when working with content management systems such as SCHEMA ST4. However, many questions arise for those switching to these systems if they have previously been using a traditional linear writing style. In this post we answer the key questions for all those who want to get to grips with modular writing.

What is modularisation?

Normally, you write a text, for example a novel, completely from beginning to end. This makes sense because in most texts, no or only a few passages are repeated. Technical documentation – as well as many other professional writing tasks – differs from this.

The easiest way to explain it is to look at the warnings in a manual. If there is a danger when handling a product, the manual must also warn of this danger. It is not enough to provide the warning in one single place. After all, the same danger can occur with completely different operating procedures and we cannot assume that the customer always reads the manual fully from beginning to end. Usually, it is more likely that you only read the part of the manual that you need at that time, so this part must also contain the warning.

In the end, this leads to the same text passage appearing again and again in the manual, which is why it makes sense to write this passage (e.g. the warning) only once and then insert it again and again in the appropriate places.

This is also useful because the text passage we have isolated in this way is probably not only needed in the manual for just one device. It is likely that other devices have similar potential hazards – so you can use the module in the manuals for many different products.

Why should I modularise?

One advantage of modularisation is already clear from the example above: an isolated (modularised) passage needs to be written only once, although it occurs in many different places in the final documents. This can save a considerable amount of time, both overall and for large quantities of documents.

However, the time saved on writing the text is only one aspect. What is much more important is that the module is easier to revise. Let’s take a look at what we need to do when we have to revise the same passage in linear texts. In this case, we first have to identify all the documents in which this passage appears. Then we have to find all the places where this passage comes up. And last but not least, we have to change the text in the same form in all occurrences. With a module, on the other hand, we only need to make the change once and the right module is then automatically applied to all the documents.

Modularisation is also desirable as it ensures that a uniform standard is always maintained. In linear writing, variations of what is actually the same text passage easily creep in. Sometimes these variations are insignificant, but they can also contain inaccuracies and errors. This can be avoided by keeping the passage in one single place and then inserting it repeatedly.

The biggest advantage of modularisation, however, is for translation. Translation costs can often be several times the cost of the original manual. Being able to reuse text due to modularisation eliminates a large proportion of the translation volume, as the same text passage is not translated over and over again. Instead, it is only translated once and then used several times in many places.

How do I get modularisation right?

Ideally, you should be able to fully compile your documents from a variety of modules. In practice, however, this will not always work, given that sometimes a text passage is really only needed once in a single document.

In this case, there are text passages that differ only minimally from product to product. This is annoying, but can be managed in many cases, as often these slight variations can be predicted systematically. For example, if only the product name or the label of a user interface element changes in the module for each final document. For systematic differences like these it is best to create placeholders in the modules. When the final document is created, the placeholders are then filled with the required variable.

The size of the modules should be as large as possible, because even though reuse saves time, it generates costs elsewhere. Each module must be found (and then managed) for the final document. However, the smaller the module, the greater the administrative burden. This can be illustrated with an extreme example: in principle, you could define each individual word of a manual as a separate module. The manual could then be assembled from these modules. However, the effort required to find the individual words would be much higher than the benefit you could get from reusing them. The same applies at all levels – the smaller the module, the higher the reuse rate, but also the higher the administrative workload. Usually, you will therefore end up with a module size of two to three paragraphs. However, there is nothing to be said against defining entire chapters as modules if they appear repeatedly in identical form in the final documents. This is the case, for example, with the instructions for disposal or the warranty conditions, which are used in (almost) the same form in all manuals. The ideal module size therefore depends on the specific document material and the reusability of the content elements.

Modularisation is a powerful tool for efficiently creating manuals. But it can also be useful to modularise other types of text. Before you decide to take this step though, you should check whether your own content is suitable for this. This is because even modular text creation involves some effort. This blog post will give you some initial tips for evaluating your content. In case of doubt, having it assessed by external content and modularisation experts can also be useful.

Leave a Reply

Up ↑

%d bloggers like this: