Thursday, March 24, 2011

Microsoft Word Now Includes Squiggly Blue Line To Alert Writer When Word Is Too Advanced For Mainstream Audience

Headline and picture: The Onion

This joke from The Onion really speaks to me. Technical writers always have to juggle between providing quickly-understandable documentation to a world-wide audience, and preserving the preciseness of the language in which they write.

Some companies have already opted for Simplified English, both to help non-native speakers understand the documentation, and to streamline translation. Controlling language goes beyond limiting vocabulary to "mainstream words" and words that can't be mistaken for a verb or a synonym. It also imposes simplified grammar and style. Although streamlining communication is clearly beneficial in the business world, one can only fear that Simplified English could slowly become the norm in more literaly realms, bringing everyone to the lowest common denominator.

The pursuit of the perfect balance between reabability and richness of content might indeed be a Sisyphean ordeal :-)

Monday, March 14, 2011

Sentence Revision

One of my Technical Writing assignments at UCBX was to find in the documents I had written in the past, sentences that were in serious need of editing; critique them; and propose a revision. Here are a few examples.

____________________________________

Original sentence:
The black rows being scanned at this stage is the total - 2 (since 2 rows are scanned for coarse offset calibration).

Critique:
There are many flaws in the original sentence:
  • The verb “is” doesn't agree with the subject (“the black rows”).
  • The subject should be “the number of black rows” rather than “the black rows”.
  • The sentence contains a passive verb (“being scanned”).
  • A pseudo-equation (“the total – 2”) is embedded into the text and should either be spelled out or turned into a real equation.
  • “Total” is very vague and could be interpreted in many different ways.
  • The sentence is overall too imprecise and lacks information.

Suggested revision:
The number of scanned black rows is equal to the pixel array's total number of black rows, minus two. (The “coarse offset calibration” algorithm scans two rows; the present algorithm does not scan them again).
          N(scanned_black_rows) = N(physical_black_rows) - 2

____________________________________

Original sentence:
During the “Sample row” sequence of the horizontal blanking, the row being addressed by the readout pointer is sampled.

Critique:
The original sentence has a long opening and it is in passive voice. It is unclear what samples the row.

Suggested revision:
The controller samples the “readout” row during the horizontal timing's “sample row” sequence. In other words the controller sets the row address bus to the “readout” pointer's current position.

____________________________________

Original sentence:
To obtain an integration time greater than the physical array height, it is necessary to program Frame Delay to a value greater than 0.

Critique:
The original sentence is too impersonal with the use of “it is necessary to”. The action is at the end of the sentence.

Suggested revision:
Program “Frame Delay” to a value greater than zero, and you will obtain an integration time greater than the physical array height.

____________________________________

Original sentence:
The problem described in this document illustrates a flaw in our current design flow, related to the fact that the padring is designed by the I/O designer rather than being designed in the digital domain.

Critique:
In the original sentence, the “related to the fact that” construct is too wordy. There are also two verbs in passive voice.

Suggested revision:
The current design flow is flawed: the digital team—not the I/O designer—should design the pad ring.