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.

No comments:

Post a Comment