CMPUT 301 Technical Writing - PowerPoint PPT Presentation

1 / 49
About This Presentation
Title:

CMPUT 301 Technical Writing

Description:

Unsplit and awkward: ... Split and correct: ... Or 'I wanted to invite Jane, Tom and Jerry and Stan tended to agree. ... – PowerPoint PPT presentation

Number of Views:36
Avg rating:3.0/5.0
Slides: 50
Provided by: csUal
Category:
Tags: cmput | and | jerry | technical | tom | writing

less

Transcript and Presenter's Notes

Title: 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
Write a Comment
User Comments (0)
About PowerShow.com