Stefan Kreckwitz, CEO of our partner Congree, describes in his guest blog article the tools that are best used to create an information space.
Solutions such as COSIMA and TopicPilot from DOCUFY are revolutionizing technical documentation. They lay the foundation for an Information Space that spans the entire product cycle. Information from development to marketing and sales, installation, operation, maintenance and finally disposal can be anchored in this space.
This virtual space is based on information modules, also known as topics. They can be used to compile and publish the desired information flexibly and for the specific application. To do this, the topics must be self-contained and provided with metadata.
Building stable Information Spaces
But how can an entire space be built with topics? Are the requirements of “seclusion” and “metadata” sufficient to create a solid, meaningful structure? To answer this question, we can transfer it to the masonry trade.
For a space made of bricks you need – besides the bricks themselves – at least:
- Knowing how to use them (= expert knowledge)
- A building plan
These elements can be transferred to the world of information.
In order to be able to build a stable space, bricklayers must undergo specialist training. Here they acquire the necessary expert knowledge: Which bricks are suitable for which building project, how they are combined and connected with each other. Authors of technical documentation also need this expert knowledge. They need to know which types of information units exist in their company. The concepts of cohesion, coherence and consistency must be familiar to them, like the mortar fort he bricklayer … because these three elements are relevant in order to fit topics together (more on this later).
The editorial plan and guide: A construction plan for the text work
Without a building plan, no solid space can be created even from the highest quality building blocks. This rule from the world of building also applies to text work. The building plan can be read as equivalent to editorial plan and editorial manual. While the editorial plan defines, which text products are created, the editorial manual gives references to the practical conversion of the text products. It defines the construction site rules of the emerging Information Space.
Additional machine-readable information – the metadata
When a pallet of bricks is delivered, it often comes with product data that a bricklayer can use to tell exactly where they are to be used. Here, too, there is an equivalent in the world of information: metadata. With them, topics can be enriched in a machine-readable way with additional information. Once the topics have been written, this additional information can be used to more or less automatically combine the topics into a large whole.
Cohesion, coherence, consistency – the linguistic mortar not only in TechDoc
Of course you can simply stack stones, just as you can simply string topics together. However, in this way neither stable masonry nor solid Information Spaces are created. Masons use mortar to build a wall out of bricks. Authors use the following three means as mortar for their Information Space:
- Cohesion: Cohesion makes a syntactic connection between two sentences recognizable – in other words: they are glued together with certain words so that the reader automatically connects them. Typical means of cohesion are conjunctions such as “and”, “but” and “because”. Also pronouns like “he”, “she” or “it” are often used. In the case of topics, it is important that the cohesion funds do not refer to something outside the topic in question.
- Coherence: Coherence refers to the contextual connection between two text modules or topics.
- Consistency: A consistent text is one that follows the same rules and norms in terms of language, style and content. In other words, this is the thread that guides the reader through the instructions. In topic-oriented texts, you must ensure that the thread is not lost.
Too little cohesion, coherence and consistency lead to the fact that the topics cannot be linked properly.
Tools: trowel, ladder, terminology tool
An expert, a building plan, stones, mortar, all this is important to build spaces and finally houses. However, the tools that make working with the materials possible should not be underestimated: Trowel, spirit level, ladder, to name just three. The same applies to writing. Software for language testing, sentence reuse mechanisms, terminology tools or similar help the authors to “raise” their content walls as high as possible.
Last but not least, tools help to overcome challenges. Everyone has different skills, different ways of working and a different style. Over time, teams change, employees come and go. But working techniques, internal know-how and team values must be passed on constantly in order to maintain continuity. Also methods are subject to the change of time, humans must adapt to new knowledge and reject old procedures if necessary, simply because there are new realizations to the topic. Such challenges occur in construction as well as in the creation of documentation – the tools ensure that standards and rules are adhered to and quality can be assured.
Of containers and living rooms
If we concentrate exclusively on the functional requirements, a functional space is created; a container. Sturdy and with smooth, unadorned walls. But is this the atmosphere we want to create for the user? How can the Information Space be furnished as a living space?
Whoever understands the information space across departments will also have to consider the requirements of marketing. Content is an important brand ambassador – which means that language can represent the values of a company and thus strengthen the brand. If, for example, a company’s products stand for precision, then this can be represented in language on many levels. The so-called “tone of voice” uses speech in the minds of potential customers to create the right “image” of a company. Just as colours, fabrics and decoration turn a space into a personal, cosy living space, Tone of Voice expresses the values, the “vibe” of a company via language. An interesting example of how a cross-company “Tone of Voice” has found its way into technical communication is the Style Guide from Microsoft. In summary, Microsoft describes its Tone of Voice: “[…] Microsoft’s modern approach to voice and style: warm and relaxed, crisp and clear, and ready to lend a hand.” That sounds more like a living space than a container, doesn’t it?