2

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?

  • 1
    Technical documents should be written for clarity, not elegance or higher style. I think the examples you provided are clear, and require less cognitive processing than the alternatives. I say stick with them and move on. – anongoodnurse Dec 11 '14 at 3:52
  • It makes navigation much easier. That would make blah. Such makes navigation blah. Verily, verily, I say unto you that it would make navigation much easier. – Blessed Geek Dec 11 '14 at 4:59
3

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).

  • @geometrikal - It's probably jealousy of my pointy ears and cute little nose. – Erik Kowal Dec 11 '14 at 11:19
  • 1
    An excellent answer @Erik Kowal. This is why I upvoted it :-) – Frank H. Dec 11 '14 at 11:47
5

Almost any word or phrase can be overused, but naming a topic (agent, "character", or subject) in one sentence and then referencing it with this in the next sentence is an excellent way to help readers through a passage with clarity and ease. It is an example of a main type of topic string, a vital stylistic element of most good writing.

It's possible that you could sometimes find a better way of phrasing, usually by lengthening the antecedent sentence by one or more clauses; but--especially when you're treating complex material--fewer lengthy sentences can help your readers process. (There's nothing wrong with well-structured long sentences, but I prefer the sentence pairs in your examples to any way I can think of combining them.)

In fiction with a lot of dialogue, we are often find many occurrences of the word said. It is not automatically better to go through these and try to replace many of them with alternative verbs (cried, mumbled, emitted etc.). Some words are repeated often without drawing notice to repetition. This (!) is because they perform their intended functions well and quietly.

0

All of the sentences seem OK to me. But if you want to get rid of the "this" at the beginning of the second sentence, you can rewrite the first sentence a little bit.

For example, instead of

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.

write

Deploying one marker buoy at the GPS location of the anchor, and another at the GPS location of the frame makes navigating much easier.

Instead of

The log files will be parsed for calibration settings and other metadata. This process can take a few minutes for very large files.

write

Parsing the log files for calibration settings and other metadata can take a few minutes for very large files.

In my opinion, the third example is probably best left as you cited it.

  • As I suppose you realize, your alternatives change the meaning of the original sentence pairs. Your first change loses the main function of the original: Instructing to deploy. Your second change loses the main function of the original: Informing that a parsing will occur. – Jim Reynolds Dec 11 '14 at 3:42
  • For the first one, you could use the passive voice: Navigation is made easier by the process. Not the greatest of sentences, though. For the second one, how about "Very large files can make this process take a few minutes"? – miltonaut Dec 11 '14 at 4:45

Not the answer you're looking for? Browse other questions tagged or ask your own question.