I appeal to all those involved in the production of content : the management of data and information, and their correct reuse in complex technical documentation, are becoming increasingly important to make work more efficient.

But knowing how to do it effectively is more difficult.

In the technical documentation it is declined in this principle: you must write your content only once, in one place (a “single source”) and then be able to:

Obviously, the ultimate goal is more efficient content production and management. “Make It Easy to Reuse”

The programmers have found themselves solving the same problems as those who have to deal with the editing of reusable content and have codified principles that can be useful to keep in mind to create reusable content.

It means you should write as simply as possible. Don’t get caught up in trying to be overly smart or show off with a convoluted paragraph. If you can express a concept in one line, write it in one line. In programming, this refers to the fact that there are always many ways to get functionality, but the simplest way is usually the best. (The educated can refer to Occam’s razor as a similar principle.)

The Don’t Repeat Yourself (DRY) principle clearly means don’t repeat yourself . This is a fairly common mistake. The very idea of ​​single-sourcing is that you should start thinking that every time you “repeat yourself” you could, as well as waste time, do something wrong.

So instead of repeating the same content in multiple places, you have to think: is there any way I can reuse this content?

This principle can be translated with the motto “don’t talk to strangers”.

You should aim to make your topics “self-contained” and, for example, be careful that don’t create “dependencies” between your content blocks. To be more concrete: don’t create links between sentences unnecessarily. And if you want to aim to make topics reusable in many different contexts (eg documentation for multiple products), then you can’t assume that one “other” topic you link to, in a different publishing context, will actually be there.

This principle refers to the idea that a topic should have only one responsibility, or task . This means that it should only fulfill one purpose.

If you mix two types of information in one sentence, it becomes difficult to reuse it. Then refactor them and break them down into smaller sentences and blocks.

According to this principle, a programmer should not develop software that implements functionality not explicitly requested. That is to say: do not try to solve a problem that does not exist. In trying to write “DRY”, some may betray this principle if they try to write as abstract and generic as possible. Apply the DRY principle only when necessary.

Where similar functions are performed by distinct pieces of code, it is generally advantageous to combine them into one leaving aside the variable parts. 

In other words: if you have the ability to make a function generic instead of specific, do so, if you make it too specific, it won’t be reusable.

In the context of technical writing, the same thing holds true: if you have the ability to make a topic more “generic” while maintaining understanding, do so. For example, imagine you’re writing about two different, but similar products. They have the same description, same safety information and so on and the only thing that differs is the model name. What this principle says is: if you don’t really need to mention the product model name, don’t! 

Leave your ego out the door and avoid writing in a crazy way.

You’re not writing to impress strangers.

Don’t try to pack a ton of concepts into one line.

If what you write is easy to read, it will be easy to maintain and easy to translate.

Remember that, in a globalized world, your texts will need to be translated. Most likely 80% of those who read what you wrote will read it with the translator’s words and how he understood it.

Try to be clear.