Thanks to EKR Orchestra’s Single Source of Truth, it is possible to write everything once and use that information in all publications on each media
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.
Have you ever heard of Single Sourcing?
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:
Use content you’ve created in multiple contexts, for example to produce documentation for different products or other variations, instead of having to copy and paste.
Publish your content in different formats and media: PDF, HTML, Mobile, etc.
Obviously, the ultimate goal is more efficient content production and management. “Make It Easy to Reuse”
The teaching of programming principles and techniques
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.
1. Keep It Simple, Stupid (KISS)
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.)
2. Don’t Repeat Yourself (DRY)
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?
3. Principle of Least Knowledge “Principle of Least Knowledge” or Law of Demeter, often abbreviated to “LoD”
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.
4. Single responsibility principle (abbreviated SRP)
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.
5 You ain’t gonna need it YAGNI
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.
6. Principle of abstraction and generalization
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.
What are you waiting for? Contact us for more information!