Exercise 13.1

Give some examples of the written documentation you’ve:

• Used to help build your team project.
• Produced for your team project.

Has this documentation been well-written? Has it been valuable in any way?

Exercise 13.2

Consider the following grammatical and stylistic exercises.

Exercise 13.2.1

Critique each of the following texts written for a guide to the CS Department.

1. CS 262 should not be taken.
2. The department hates CS 262; it’s wildly unpopular.
3. Your going to hate CS 262; its alot of work because their to many mindless details two attend too.
4. Come to the CS 262 exam classroom with your mobile device.
5. Don’t use negative imperatives in CS 262.

Exercise 13.2.2

Critique the grammatical style of the following list^*.

Approaches to writing effective comments

1. Writing self-documenting code.
2. Don’t document the obvious,
3. Comments with simple formatting near to the code they document

^*These (valuable) guidelines are (poorly) adapted from J. Atwood “When Good Comments Go Bad”.

Exercise 13.3

Start with the following, clear, concise command:

Go directly to the classroom.

Without changing its meaning, modify this statement as follows.

1. Change it to passive voice.
2. Remove all (the) articles.
3. Split an infinitive.
4. Obfuscate a phrase.
5. Add ambiguity.
6. Violate other selected stylistic guidelines.

Exercise 13.4

What was Postman’s fifth idea and do you agree with it?