Skriftlig Info ➜ Methodology ➜ Modular writing ➜ The content of an information element
The purpose of such text modules is, among other things, to save time. The fact statement(s) used allows specific information to be repeated without risking errors in any updates. They can also be used to reuse structure, repeating lists of topics and/or related topics. They are particularly useful if your text needs to be translated into one or more other languages.
You decide what each information element should contain. Your tool may set some limitations.
A typical information element can contain:
If you create many technical manuals. Several of them will probably contain different types of notes, and you will probably repeat some of them many times. You can then create an information element for each note, and you can retrieve and reuse this element as often as necessary.
The use of such generic text modules depends very much on what kind of tool you use and what kind of functionality it offers. Text modules are often saved as separate files. Keeping track of these files can be challenging. In DITA, a separate function called conref is used. This function allows you to retrieve information from a "library". This means that you can, in principle, collect many generic text modules in the same XML library document. Experience shows that this is not a good idea, small files that contain little information are preferable.
If you need to use an image of the door on a washing machine, this image can be established as a separate information element. Every time you need the image, you can retrieve and reuse the same file with the same photo. If you use several different doors, each image in the file can be profiled. You can then retrieve the same file regardless of which washing machine you describe.
If you describe a product that uses electronic circuit boards, you probably have a note or warning against static electricity. If you have 35 different circuit boards, it is quite silly to copy this text as many times. What will you do if you want to change it, for example by inserting an illustration or a hyperlink to additional information?
Introduction to DITA publishing
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.
GR 2023-01-18