Organizing the flow of a technical document
What is your story?
The most common problem for technical documents and presentations is that people focus too much on technical details. However, every document should tell a story. Your most important goal is to make sure that your readers care about your story. Otherwise, you will not be heard.
Technical writing is still writing
If you are in the technical field, your work will be communicated through scientific papers, reports, posters and presentations. It is true that people will be reading what you have produced for its technical content, but if you just line up technical facts one after another one, you will not be able to give your message. Your documents should clearly explain what you did, need to be easy to follow, contain sufficient details to enable another person to replicate your results, and essentially convince the reader of your work.
Your document will be telling the story of how you have solved a particular problem. If you want that people read/listen to you, make sure that you explain them, why this problem is important. If people do not see the problem they will not understand or appreciate your solution.
Unfortunately, most technical writing treats this part as a formality, there are set phrases likeIf you do not put an effort into it, trust me, it will show.According to forecasts by company so and so [ref], the worldwide energy consumption for health related IoT devices will exceed 2.3TWh.
You have probably spent considerable effort in your work to get your results, and are eager (or obliged) to share the outcome as soon as possible. But your readers/listeners are not like you. They do not know you, have probably not spent the same amount of time on these problems and are not convinced that what you are about to explain is interesting enough to warrant their time. It is your job to keep your readers/listeners involved. They need to understand why you think the problem is important, so that they can follow what you did.
In almost all cases, people will have tried to solve the same problem in one way or another. It is very very rare to be the first one to have tackled a technical problem. Sometimes we are too focused on our own work and want to come to the fun part where we discuss all the cool things we have done. Similar to the motivation, the state of the art is oftentimes written without much attention. In some way, people become defensive, see this part of their story as a hurdle, are afraid that their work will not stand out enough, so they go thread through it without much care. In fact, this part is an opportunity to involve your readers/listeners in your thought process.
Technical people are trained to be suspicious, they are attracted to solving problems. So explain them a problem, they will immediately try to imagine a way of how it can be solved. The state of art part actually catches them in this process, and guides your readers/listeners through the steps that others who have spent time on it did. A problem becomes more interesting as the amount of effort to solve it increases. If you are solving a worthy problem, many people will have attempted to solve it before you.
What the state of the art actually helps is to structure the problem, it helps you to steer the focus from a more general problem (energy efficiency), to a more specific one (energy efficiency in health monitoring systems relying on energy harvesting through solar panels) and helps you with the motivation further. As you tell the history of the problem, you will be branching off and specialising step by step. In a way you will be walking towards your solution and explaining why you think some of the work of others worked and why it didn't
If you want to be respected, you should also respect others. It is their work that enabled you to pursue your own. This story is an important part of the narrative, what is it that was missing from the work of the others. What results were not good enough, or where do you think there was more work that could be done. If you can keep the people interested, if they think that your summary is good, if they agree with your path they will be more likely to soldier on. They will get your mindset that motivated you.
Now that we have agreed that we have an issue to solve, and we have seen what others did so far, we need to establish some ground rules. * How do we solve these problems.
- What theoretical work is needed to analyze and solve them.
- How do we measure the quality of our solutions.
For most problems, there will be more than one possible solution especially in engineering sciences. List these possibilities, help your reader follow your thought process.
There will be reasons why you preferred one solution over the other. Explain how you judged them, what motivated you to choose one over the other. Notice that you will have to rely on the theory ground work you laid just before and use the performance measures you have just described to make your point.
The key point here is not flip-flopping between alternatives. Establish a good flow in your reasoning and bring the readers to the solution that you want to explain. Do not go back and forth between alternatives or feel compelled to stick to the chronology of your work.will not keep the readers engaged. It is not about hiding what you did, but you want to focus on your solution. Failures along the way are part of the story, but do not frustrate the reader, make sure the focus stays on the storyI tried this, did not work, then I tried this did not work, so I tried this did not work
is a better formulation that will keep the readers focusedAfter trying a number of alternatives (listed in Table X) the best solution was..
Finally this is the part where you explain your work. Try to use a classic introduction, development, conclusion cycle for this explanation as well.
Now that you have explained what you did, it is time to compare to previous solutions. The results are there to convince the reader of the merits of your solution when compared to other solutions. It is important to also explain how the various results were obtained, to allow critical readers to verify your claims if needed.
Once again, it is important to build towards a conclusion and avoid flip-flopping at all costs. The reasoning could take a few detours, but the path must be flowing and the reader should be able to follow it easily.
When presented with a 100 page document, people who do not have the time will read:
- Abstract: is the summary that tells you what the problem is and what your main achievement was
- Conclusions: that tells what you have learned after finishing this work.
It is actually, the last two things you will end up writing. They will be similar in one way, but the conclusion spends more time on the results, while the abstract also has to convince the reader to read on further and therefore needs more emphasis on motivation.