CMPUT 301 Technical Writing

1
CMPUT 301 Technical Writing

• Lecturer Sherif Ghali
• Department of Computing Science
• University of Alberta

2
QA

• Is technical writing as important as program
  writing?
• Yes English is your most important scientific
  instrument. Use it with precision.
• Why is a non-native speaker giving this talk?
• Non-native speakers learn the rules then develop
  the ear whereas native speakers develop the
  ear before learning the rules.
• Corollary A non-native speaker is more likely to
  know why one version of a sentence sounds better
  than the other (and is also more likely to get it
  wrong).

3
Content

• Word usage
• Punctuation
• Disappearing rules

4
Word Usage

5
Incorrect Usage of which

• Abundant in Dix et al. For example
• In previous chapters we have discussed
  methodologies and models which support the design
  of usable interactive systems. (p.406 (1))
• Correct
• In previous chapters we have discussed
  methodologies and models that support the design
  of usable interactive systems.

6
More Pitfalls with which

• The user can select any number of points on the
  drawing surface which the system connects with
  straight lines. Dix et al. p. 297 (1)

7
Split Infinitives

• The rule of thumb never split the infinitive.
• This rule is now archaic and can be broken ? but
  do it judiciously and make sure the result is not
  awkward.

8
Awkward Unsplit Infinitives

• Unsplit and awkward
• It is relatively easy to get a system
  automatically to record user actions at a
  keystroke level Dix et al, p. 428 (-1)
• Split and correct
• It is relatively easy to get a system to
  automatically record user actions at a keystroke
  level

9
Awkward Split Infinitives

• Split and wrong
• The user is urged to not press the reset button
• Not split
• The user is urged not to press the reset button

10
Usage of However

• It is never justified to use However as the first
  word in a sentence In that usage it is always
  superfluous.
• As a first word
• Consider replacing However with But
• Reword so that the stress arises from the meaning
  rather than by an artificial emphasis.

11
Usage of However

• As the BNF notation has been described in detail
  in Chapter 6, we will not repeat the description
  here. However, in order to compare it with other
  dialog description notations, we recall that BNF
  has two connectives to denote sequence and
  choice. However, note that the use of as a
  symbol for sequence in Chapter 6 is not standard
  Dix et al. p.313 (3)
• Both Howevers can be removed with no change in
  meaning or emphasis. The emphasis should be
  embedded in the meaning.
• In this case Howevers are included merely to
  hide a choppy writing style.

12
Usage of However

• Dix et al p. 313
• 6 However,
• 2 Unfortunately,
• 2 For example,
• 1 In addition,
• 1 In particular,

13
Avoiding Sexist Language

• Not-very-good solutions
• Alternate between male and female forms of speech
• too messy in writing except on a chapter basis
• confusing for the listener and requires
  unnecessary attention from the speaker
• Use awkward (but now accepted) grammar
• The speaker should ensure that their fonts are
  legible.

14
Avoiding Sexist Language

• Good solutions
• Use the plural
• Speakers should ensure that their fonts are
  legible.
• Use generic forms of speech/writing
• When designing slides, one should ensure that the
  fonts are legible.

15
Avoiding Sexist Language

• Use your judgment
• A man succeeds by striving is offensive.
• The programmer has to be familiar with the
  library he is using is harmless.
• In any case, it is better to err on the side of
  using sexist language (by using a gender opposite
  to the writers sex) than to use incorrect
  grammar.

16
The this syndrome

• When using this, always ensure it is entirely
  evident what it refers to.
• The rules are executed again, when the condition
  matches the state, but, this time, the attributes
  are not changed by this alone. Dix p.316 (-2)

17
Avoid Informal Writing

• Im gonna write the document is indefensible
  (even in an email).
• Really, typically, are too informal
• This algorithm is really fast.

18
Ending a Sentence with a Preposition

• Whats wrong with the following
• Comments and the code they provide commentary on
  drift apart over time. Lippman Lajoie, p. 18

• Better
• Comments and the code on which they provide
  commentary drift apart over time. Lippman
  Lajoie, p. 18

19
Ending a Sentence with a Preposition

• Watts 3D Computer Graphics 2000, p.183, Sec.
  6.4
• We now look at how we determine the actual pixels
  which we require intensity values for. (awkward)
• Better
• We now look at how we determine the actual pixels
  for which we require intensity values.

20
Ending a Sentence with a Preposition

• The rigid rule of never ending with a proposition
  is archaic.
• Trust your ear and choose.

21
Dates

• Strunk White recommend
• 30 May 2002
• Better than
• May 30, 2002

22
Hyphenating Adjectives

• Hyphenation is sometimes quite important
• "NOTE Lear Siegler does not service ADM-3A
  kits. If service or technical assistance is
  needed, your dumb terminal dealer should be
  contacted.
• low-level API, not low level API
• view-frustum culling

23
Hyphenating Adjectives

• Hyphenation is sometimes quite important
• Compare
• Keep Space Weapons-Free UN Urges (News headline
  on 30 August 2001).
• Keep Space Weapons Free
• Compare
• There is a little publicized research grant
  available.
• There is a little-publicized research grant
  available.

24
Hyphenating Adjectives

• Longer words do not require a hyphen
• CACM June 2000 cover
• Physically Based Computer Animation

25
Capitalise after a Hyphen

• We therefore ask the following question Is it
  possible to triangulate a simple polygon in
  linear time?

26
Latin-Derived Plurals

• We aborted the experiment after discovering that
  the data collected were riddled with errors.
• We are unable to release as we believe that the
  topmost strata in our system are not sufficiently
  debugged.

27
Countable vs. Uncountable Sets

• There is less sugar in that jar.
• There are fewer people in that room.
• The refined mesh has more vertices.
• The refined mesh has fewer vertices.
• The course will be canceled unless enough people
  register.
• The course will be canceled unless sufficiently
  many people register.
• Due to our elaborate quality control, we release
  fewer patches than the competition.

28
Watch for Transitive Verbs

• This moderate time consumption allows to compute
  gossiping schedules for networks with more than
  10,000 Pus.

29
False Parallelism

• Programming Intuition
• ab a and b must be of the same type
• Incorrect
• Applicable rules belong to the rental, not
  customer

30
False Parallelism

• Variations will result from having partitioned
  classes and incorrectly predicted the effort
  needed for each.
• Parallelism between
• the following doesnt stand
• having partitioned classes
• incorrectly predicted
• the following neither
• partitioned classes
• incorrectly predicted

31
False Parallelism

• False parallelism
• Variations will result from having partitioned
  classes and incorrectly predicted the effort
  needed for each.
• Solution duplicate having
• Variations will result from having partitioned
  classes and having incorrectly predicted the
  effort needed for each.

32
whether vs. if

• I wrote that the computing industrys blunder
  rate is far higher than it should be, and we must
  take professional responsibility for it. No one
  reacted to this assertion, leaving me unsure if
  the silence sprang from collegial agreement or
  dismissive contempt.
• -Holmes, IEEE Computer, July 2002

33
whether vs. if

• I wrote that the computing industrys blunder
  rate is far higher than it should be, and we must
  take professional responsibility for it. No one
  reacted to this assertion, leaving me unsure
  whether the silence sprang from collegial
  agreement or dismissive contempt.
• -Holmes, IEEE Computer, July 2002

34
Substitute vs. Replace

• A is replaced by B
• B substitutes A

35
Use the Subjunctive for Impossible Conditions

• If this algorithm were more concise, we would
  have implemented it in microcode.

36
Verb Order

• Can you tell me what the difference is?
• Can you explain to me what the difference is?
• Can you explain to me? What is the difference?

37
which vs. that

• We describe a class that encapsulates our new
  algorithm.
• We describe class FooBar, which encapsulates our
  new algorithm.

38
Punctuation
39
Punctuation Order

• This is a quotation.
• The author tiringly used the expression to be or
  not to be.
• The author tiringly used the expression a
  turning point in our civilisation.

40
Punctuating Conditional Statements

• If it is raining, I shall take an umbrella.
• I shall take an umbrella if it is raining.

41
Serial Commas

• From the Chicago Manual of Style FAQ
• Hello. In the sentence "I went to the store to
  buy eggs, milk and cheese" do you put a comma
  after "milk"? What is the standard now for comma
  usage after the second-to-last item? I have seen
  such sentences both with and without the comma.
  Thanks.

42
Serial Commas

• Answer
• Chicago style is to put a comma there (it's
  called a "serial" comma). There are times when
  that comma is necessary to avoid awkwardness or
  ambiguity "My favorite combinations are green
  and yellow, blue and purple and black and red."
  Or "I wanted to invite Jane, Tom and Jerry and
  Stan tended to agree." Since it is sometimes
  needed, and is never wrong, the simplest way to
  impose consistency without having to stop and
  think about each instance is to form a habit of
  adding the serial comma.

43
Citations

• Yamaguchi 5 proves the correctness of the
  algorithm shown in Figure 2.
• Notice
• Statements should remain correct if the reference
  (5) is removed. It is poor style to write
• In 5, Yamaguchi proves
• Particularly ugly for superscript references
• In,7 the authors claim the following.

44
Citations

• Yamaguchi 5 proves the correctness of the
  algorithm shown in Figure 2.
• Notice
• Capitalise references Figure 2, Table 7,
  Equation 23.
• An informal reference (the preceding figure) is
  not capitalised.

45
Divergence from German

• Does anyone know, whether I need a different
  viewer?
• Literal from
• Weiss jemand, ob ich ein andere viewer Program
  brauche?

46
Disappearing Rules

47
Subjuntive

• If I were you,
• slowly gaining acceptance
• If I was you,

48
Fewer vs. less

• Grocery store lines should write
• fewer than 6 items
• gaining acceptance
• less than 6 items

49
References