Remember, you are not writing a crime fiction! This is a very common mistake in technical writing, and is a very annoying one as well, especially for the reader! It is common practice in literary genres such as crime fiction that the writer follows a very secrete plot when telling the story. The writer does not want to reveal any secrets that will spoil the plot. This approach should be strongly avoided in technical writing!
You must reveal all your secrets as soon as possible! I am not sure what the reason for this annoyance is, i.e. why readers get annoyed when technical writings are mysterious. Maybe the reason is that the reader of a technical report/paper is not expecting to be confronted with a crime fiction, and they feel cheated. Another reason in my view is due to the complexity of technical text; if the user does not have a clue of the goal of the text, it is difficult to follow the text and use the sentences to build a mental model of what the writer wants to say.
There are many ways of revealing secrets early in a report:
- Get institutionalized! Make it a habit to sum up whatever you are trying to say in 1-2 sentences in the beginning of your block of text and summarize in 1-2 sentences in the end of your block of text. E.g.: start your paragraph/section by saying “We will develop component A to do B because..” then describe your component, and then summarize: “In this section we developed component A to do B because…”
- The abstract and the conclusions: The first and the best place to reveal your secrets is in the abstract of your report/paper. The abstract should tell in short what problem you addressed, what method you used, and what results you achieved. So no secrets left! Also a good idea to summarize your revealed secrets in your conclusions so you are sure you don’t leave anything to guess work and fantasy.
- The chapters: Introduction to each chapter should state shortly what secrets you intend to reveal in that chapter, and the summary should summarize the revealed secrets.
- Sections and paragraphs: Each section and even each paragraph should have a short sentence in the beginning to give a hint of what you intend to say in it.
- Don’t hide! Never hide stuff in technical and scientific text!
PS: This is the secret I did not reveal until now: I strongly believe the reason for writing mysteriously is that the writer does not have a clue of what he/she is writing about!