Clear Technical Writing
Engaging Action

Readability 1

When we read, one part of our mind is detecting symbols, another part is parsing syntax, and another part is assembling the thoughts of the writer. It's hard work.

When we write, we should help the reader stay focused, by avoiding impediments that spawn extraneous mental effort.

Announcements

When we call extra attention to a subject, we unavoidably remove attention from the verb.

It is the firewall that protects our systems.

The extraneous thought in the reader's mind is:

Why is this noun so important?

The sentence without the announcement is more engaging because it does a better job of presenting the action in the sentence.

The firewall protects our systems.

The phrases it is and there are are often used to begin an announcement.

There are two modules that were recently updated.

Two modules were recently updated.

Opinions

When you're sure the reader wants to know how you feel about something, it's okay to include words that invite discussion about your opinion. Otherwise, play it safe and omit those words.

Interestingly, that module was not tested.

The extraneous thought in the reader's mind is:

Why does the author feel this way?

The sentence without the opinion is more engaging because it directly presents information without qualification.

That module was not tested.

Note: Be very careful with the word obviously. It is seldom truly needed, and it is too often interpreted as an insult.

Silos

Sentences that stand alone like silos can cause subtle extraneous thoughts.

New advancements in fighting cancer have been identified by doctors studying monoclonal antibodies. Doctors take cells from your blood to design monoclonal antibodies. They have designed antibodies that attach to a toxic substance that kills the cancer.

When reading the second sentence, the extraneous thought in the reader's mind is:

How does this relate to the prior sentence?

That extraneous thought is much less likely to occur when someone reads this version of the paragraph:

New advancements in fighting cancer have been identified by doctors studying monoclonal antibodies. These antibodies are designed from a sample of your blood taken by a doctor. They have designed antibodies that attach to a toxic substance that kills the cancer.

Why? Because now the second and third sentence both start with something that was talked about at the end of the preceding sentence.

... antibodies.
→These antibodies ...
... doctor.
→They ...

Instead of silos, the sentences are now presented as a cohesive train of thoughts.

This is most easily accomplished by placing new information at the end of sentences, especially when it's new technical information.

Edit your writing by underlining things that might prompt extraneous thoughts in the mind of your reader.

It was an overheating problem that led to our research. Our goal was to reduce heat transfer to turbine blades. We built a wind tunnel to prove a laminar reattachment bubble was possible. Within a two-dimensional flow, we created separated laminar boundary layers. We varied flow characteristics (free stream turbulence level and surface pressure distribution) and inevitably demonstrated the criterion for a laminar bubble.
  

Lesson: Readability 1
Module: Engaging Action
Course: Clear Technical Writing