§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