P415/style
§P415
Projects - Remarks on writing
Writing component of the project
-
Bear in mind that, owing to time limitations, the primary factor
in evaluating your project is not the work itself, but your presentation
of it. Consider carefully how to apportion you remaining efforts,
between completing more goals or crafting a clear, cogent explanation
of what has been (or remains to be) accomplished.
-
Remember that your audience is, for the introduction, computer science
majors, and for the remainder, P415 students. This audience can
read and comprehend code fragments (if clearly indented and cleanly
organized), understand mathematics. and also knows how to use PVS.
You need to find an appropriate level of presentation, not too much,
not too little. For example, it is not necessary to include a PVS proof
tree or discuss routine proof steps. The .prf files are part
of your data so an interested (or skeptical) reader can step through your
proof. On the other hand, if there is an interesting issue, a discovery,
or a subtle insight that you want to discuss, showing just where it arises
in a verbatim display of the proof sequent, along with a clear discussion
of course, can be a good way to illustrate it.
General comments on style
-
The handbook The Elements of Style by Strunk and White should be
on every writer's bookshelf. It is available
on line and elsewhere, but it
less a reference than something you should simply pick up and read from
time to time. I recommend buying a copy.
- Edit for style.
Your last editing pass should be strictly concerned
with style. Look for patterns, good and bad, that have strictly to
do with English communication. A reasonable goal is to eliminate
all unnecessary words, syllables and characters. Looking at "drafty"
writing is clear evidence that written English is a poor reflection
of active thought.
- Use present tense.
If you feel it is important to tell the reader that
what you are describing is work done in the past or to be done in
the future, say so once at the beginning.
Good technical writing is economical, and present tense is the most
economical form of English (fewer words, syllables, characters).
- Avoid passive constructs.
Instead of "the performance of the algorithm"
use "the algorithm's performance". Again the reason is economy. The
word "of" often flags passive constructions, so in your final editing
pass, examine every occurance and see if it can be eliminated by
a more active voice.
- Take care when using "we".
If "we" refers to your group, fine, but if it includes the reader,
be cautious. Readers may react negatively to having your conclusions
or opinions imposed on them. They may
be prompted disagree or challenge these conclusions.
"We now move to the induction step," is all right (as long as you've
announced earlier that you're doing an induction); but
"We can now see that blue is a far better color than green," only begs
an agument from the innocent party (the reader).
- One thought, one sentence.
Good technical writing is straightforward, if not always simple.
The need for precision may dictate complex phrases and logical
structure. Do not compound the difficulty with complicated English
constructions. Stick to direct, subject-verb-object sentences. Eliminate
after-thoughts and side comments, even footnotes. Do not explain
alternatives you did not follow, or failed attempts. If these raise
important points, save them for the conclusion.
- Say what you are going to do, do it, then say what you did.
I was once given this advice as the ideal outline of a research paper,
but I think it applies as well at finer levels of writing. There is
a natural desire to build toward a surprise ending, especially when one
feel they are presenting something original and clever. Suspense is never
a risk worth taking. The object of technical writing is to explain, which
is best accomplished when the reader can anticipate the next step and
when the writer takes the time to consolidate and review key ideas.
Please share your ideas about good writing with me....SDJ