I have to write technical documents such as manuals, reports and journal articles.
Recently, I find myself beginning sentences with “This” a lot of the time. For example,
Deploy one marker buoy at the GPS location of the anchor and another at the GPS location of the frame. This makes navigating much easier.
or
The log files will be parsed for calibration settings and other metadata. This process can take a few minutes for very large files.
or
If new batteries have been inserted, the magnetometer must be recalibrated. This operation is similar to the recalibration often required when using a smart phone compass.
Are these sentences okay or are there any other sentence constructions that read better? Should I just accept it and move on?
Answer
There is a distinct advantage to continuing to do what you have been doing so far.
This is that the repetition of the pattern
Instruct the reader to perform an action,
immediately followed by
Description / comment regarding the action’s result and / or benefit,
lessens your readers’ cognitive load: they are not constantly being required to perform the additional work of interpreting a variety of presentational formats and sentence structures in order to sort the instructions from the descriptions, or to understand their mutual relationships.
The way you are currently presenting information to readers enables them to know immediately what is being expected of them, and why.
The fact of a sentence starting with “This” is actually a useful signal to your readers that what is about to follow is probably a description or comment regarding an action that you have just asked them to perform.
This aspect of the presentation of material is one important way in which technical documentation differs from literary fiction.
Depending on the style of the fiction writer, part of the pleasure of reading fiction depends on being surprised with unexpected juxtapositions and little puzzles, some of which are created or made more intriguing by varying the way the material is presented to the reader.
In your case, you are (or should be) aiming for the opposite result: the predictability of your presentation and the clarity of your readers’ understanding will go hand-in-hand. The relative brevity of sentences and repetitiveness of format in your documentation reduce the scope for creating unintentional ambiguity.
It is worth bearing in mind one important reason for avoiding ambiguity in technical documentation: not only is it annoying, it can even be dangerous or damaging if a reader is confused into performing an incorrect action (such as energizing a circuit which should not be energized).
Attribution
Source : Link , Question Author : geometrikal , Answer Author : Erik Kowal
