When explaining complicated ideas, your goal shouldn’t be to dumb things down – you’re here to teach, not to help people avoid learning. But the best way to teach is not to start at the expert level and hope your readers follow along, it’s to start at the bottom and layer it up. Give people a tiny amount of information, then a tiny amount that builds on that, and then a little more and a little more.
As an engineer you probably know this, but because you’re a field-expert, not a writer or a beginner, you may not build your layers correctly. Primarily, I suspect your definitions of “common knowledge”, “tiny amount of information” and “gaps that can be filled by the reader” are too broad.
Luckily, constructing layers is not an art-form; it’s a simple technique, and you don’t have to be a writer to do it correctly. So here’s the recipe.
First, find the top layer: the bottom line of what you’re trying to say, and I do apologize for using contradictory metaphors. Write down all of the concepts, procedures and flotsam that the reader must know to understand the bottom line. For example, if you’re explaining how to wire car alarms, the bottom line will be the actual wiring, but previous layers may include explanations of how to reach the wires, how to connect and disconnect wires, what the alarm hardware looks like and so on.
It’s natural here to assume that some things are common knowledge, but unless you know that all of your readers have a certain background your best bet is that they are competent adults, nothing more. So in the car alarm example, don’t remove the section about how to connect wires unless you know that your readers are all electricians.
For each item on the list, create another list of everything the user must know to understand the item. Some of this information you already had on the list from the previous step, and so lists will merge; some will be added now, and might spawn more lists. Moving to a software example, if you are explaining how to connect to an API, one of the concepts you may have originally listed is XML. You might now decide to create a new layer for XML (and explain concepts like open tags), or you might decide to merge the XML and queries concepts into a single list.
Arrange each list of concepts from the most complicated item(requiring the most knowledge to be understood) down until its most basic support. Each organized list is a layer of your explanation.
Within each layer, introduce new concepts one at a time. For each concept, give context and consider giving an example. Check again and again that you’re using either layman’s terms or terms you’ve already explained. Go back and add missing concepts, unless they can be explained in just a few words (perhaps in brackets), in which case you can consider leaving them within the current concept.
When all of the concepts tied to a complicated concept or procedure have been explained, it’s time to explain the complicated bit. Do not add any new sub-concepts here – this bit should explain only the connection between established concepts. For example, if you’re explaining what parameters each API query must contain, this is not the place to explain basic concepts like API, queries and parameters. They should have already been introduced, clearly and fully enough to use them now without elaborating.
You now have all of your layers. If you did this correctly, the bottom layer (and perhaps some of the middle ones) begins with a concept that can be explained fully in layman’s terms, and moves on to ever more complicated ideas, following your list. All layers together build towards the last one – and the bottom line. Remember that the order in which you handle the layers matters in the same way that the order of items within each layer matters – they should build on each other, and the reader shouldn’t have to jump backwards and forwards.
As a final tip, try not to leave miles between related concepts – there is only so much people remember. If you have to re-use a concept that you last touched on fifty pages ago, be kind and give a few words, even as a footnote.
If your list was orderly and detailed enough, your writing should have a logical progression that starts at introducing the basics and then builds on them. You will eventually reach your bottom line with all the required information already given.