Tips on Technical Writing: The Glossary Is the North Star
Never underestimate words, even more when it comes to technical writing.
Technical writing is about educating the audience enough to make them able to complete a task.
The educational facet is the key, which means accompanying someone from the uneducated state to the educated one; this is a journey that requires a coach (meaning a horse-drawn carriage) to move.
In this article, I want to share with you what this coach is. So, no spoiler, and get started!
In the beginning, was the word
As every other professional in our fast-pacing world, technical writers are constantly under pressure. The consequence is that there is no time to think theoretically. Even more, the analysis of the foundations of a profession seems a waste of time, which is a loss, as we will see in a moment.
When it comes to technical writing, there are two levels of foundation:
- Foundation of the craft: This is the knowledge that the technical writers apply regardless of the matter.
- Foundation of the topic: This is the knowledge that grounds the specific-per-matter documentation that the technical writers deliver.
What I want to explore here is the foundation of the topic as a pivotal part of the foundation of the craft.
In the beginning, was the word
As technical writers, usually, we are not experts in the content we write. So, any document we deliver requires a learning process of research and interviewing the subject matter experts. That learning process leads us to build the foundation of the topic.
What are the building blocks of any knowledge foundation?
Words. Namely, the words that point to the foundational concepts of the topic.
For technical education, use a mathematical approach
We, as human beings, are so used to words that they often escape our attention. The consequence is that we do not focus on their precise meaning but on the habit we have of them. That is what technical writers must avoid.
In general communication, it may be enough to convey an all-around meaning to the audience. Instead, technical communication requires precision, word by word.
So, what?
The best reference for a precise language is mathematics because it is a formal language, where the audience always knows whether a statement is:
- An assumption, or
- A consequence.
This distinction is paramount for technical content because it declares to the audience which pieces of knowledge they are supposed to own to understand the writing; it answers the audience’s question: “What should I read first to get from the writing what I need efficiently?”
Be aware that if the writing does not explicitly declare its assumptions, the audience must try to discover them. Would the audience love to make this extra effort?
Technical writing audiences are always busy with tasks other than reading, so they would not appreciate any extra effort!
Back to the mathematical language as a model, how does the technical content structure make it easy for the audience to consume the assumptions whenever needed?
The glossary is the answer.
Glossary is the North Star
I started the article by highlighting that the mission of technical writing is
[…] accompanying someone from the uneducated state to the educated one.
Then, the technical content is a journey that needs a North Star to proceed safely. The glossary is this North Star, a reference always available to clarify and confirm where to go next.
How?
The glossary provides the matter-specific meaning of every single word.
Written and spoken words are the building blocks of any documentation, together with visuals; this means that every time a word has an ambiguous meaning or, even worse, it does not have a written definition, then documentation fails to deliver knowledge.
Instead, the glossary ensures that
- Each word has a formal definition, and
- The network of definitions is a coherent mapping of the matter.
In other words, the glossary provides the dots and their connections: the resulting map is an educational representation of the matter that technical writings describe.
Back to the mathematical analogy, the role of the glossary is double:
- On one side, it defines the concepts through the words, and
- On the other side, it represents the relations among the concepts, providing a powerful language to deliver a broad picture of the matter to the audience.
Conclusions
Often, succeeding in communication means adopting as much common sense as possible, which also applies to the glossary.
In fact, what is best than agreeing on the definition of words to understand each other?
Many people emotionally reject precision as if it were a pedantic attitude; nevertheless, strict language is the only possible solution to deliver adequate technical documentation.
So, be patient and go through the definition of each word, and build upon this foundation called glossary, the edifice of knowledge!
If you enjoyed my article and found it helpful, please consider joining Medium through my referral link: you’ll support my writing and get into a sea of knowledge. No extra costs!
