Be it a Technical Writer creating documentation, a Teacher working on learning materials, or a Scientist preparing a research paper— oftentimes, we all struggle to introduce new concepts and terms to the audience. We can spend hours in front of an empty white piece of electronic paper trying to figure out the best way to put a complicated subject into simple words and coherent structure.
Where to start? Is it too much information for the beginning? Or too little?
To save my (and, hopefully, your) time answering those questions, I came up with an approach that I apply in my work when it comes to explanatory documentation. The approach is enclosed in the abbreviation DEPE and implies providing
- D — definition
- E — explanation
- P — purpose
- E — examples
for any new term being introduced.
D — definition
First things first. When a new concept shows up, a rule of thumb is to write this ‘X is a …’ sentence immediately. In non-scientific and non-official documents, use unambiguous words and simple grammar structure. Especially with terms that are not intuitively clear. The reader will have to put effort wrapping their mind around the meaning, don’t force them to unravel sophisticated grammatical knots.
Of course, sticking to simplicity won’t work in academic fields or legal papers. But in user manuals, internal documentation, and learning materials, it’s something to aim for.
In general, mind your target audience when you develop definitions. For example, if you are teaching five-grade students biology, you won’t start a lesson about photosynthesis with a definition from Wikipedia:
Photosynthesis is a process used by plants and other organisms to convert light energy into chemical energy that, through cellular respiration, can later be released to fuel the organism’s activities.
A much more appropriate introduction would be:
Photosynthesis is the process when green plants use sunlight and water to turn carbon dioxide into oxygen.
E — explanation
There are two types of explanations that can be given after you defined a term:
- Elaborating explanation
When you came up with a definition, let 5–6 people familiar with the field but not related to the subject read it and observe their reaction. If they frown and start asking you questions, you may need to dig a little deeper and give 1–2 sentences to answer those questions. However, make sure you don’t overwhelm the reader with too in-depth details. Now, during the introductory stage, all we want is to ensure a primary understanding and spark an interest to study the subject further. - Clarifying explanation
I won’t say it is a good practice to define one term using other unknown or unclear terms. However, sometimes you can’t help but do so. In this case, explain those auxiliary concepts in the following paragraph.
For our definition of photosynthesis, I would remind them what ‘carbon dioxide’ and ‘oxygen’ are:
People and animals intake oxygen from the air when they breathe in and release carbon dioxide when they breathe out.
❗ If your elaborating or clarifying explanation takes more than 1–2 sentences, it’s better to paraphrase your definition.
By the way, there are cases when you can skip this first E in DEPE:
- the provided definition doesn’t introduce any new concepts
- your target audience is familiar enough with the subject, and you are 99% sure they won’t require additional clarifications.
P — purpose
When you explained WHAT a term represents, the next step is to create an association in the reader’s mind with WHY to use the term. A purpose it serves or, better, a problem it solves.
With such an association, it will be easier to remember the concept and hold it in memory longer.
So, kids are more likely to answer what photosynthesis is a day after the lesson if they have an understanding of its role:
Photosynthesis is necessary for life on Earth. Without oxygen produced by plants during photosynthesis, we couldn’t breathe and wouldn’t exist.
Sometimes, it may be useful to put a purpose before a definition. In such a way, we gently bring the reader to the subject, so that they understand why this term showed up in the first place.
E — examples
I always advocate providing examples, and here they are as pertinent as ever!
Examples help solidify understanding of a new concept by augmenting this WHAT-WHY association to the WHAT-WHY-HOW one. They can be
- use cases
- diagrams, infographics, or any other type of visuals
- comparison tables
- code snippets (for developer documentation)
- etc.
Depending on the type of documentation you create and the term you introduce, you may need a specific type of example. Make sure that the type you decided to leverage is cost-benefit effective — the example will be most helpful for readers and won’t take you too long to implement it.
For our photosynthesis example, it would be nice to follow the purpose with a picture like this:
Why does DEPE work?
Introducing a new concept is difficult for both reader and writer. For the reader, it may be hard to grasp the new idea and form a solid understanding of it. The writer’s pet peeve is how to deliver the knowledge in a comprehensive way.
DEPE implements the principle of ‘quick wins’ for both sides:
- The reader gets a primary understanding of a concept without being bombarded with excessive information. After reading 4–5 sentences, the foundation for understanding is formed, dopamine from the first success is released as well as a willingness to dive deeper into the subject.
- The writer gets the foundation for developing the documentation further without spending much time reinventing the bicycle — pondering about a proper way to introduce a new concept.
P.S.: In this article, I do not provide any programming-related examples. It’s because sometimes you want to take a break from work and get closer to nature 😉
