Transcript Example

A Few Rules from "A Handbook for
Scholars"
Notes on Technical Writing
Toward Clarity and Grace
CPIT695
Dr.Buhari
Reviewed by :
Name
ID
Paper
Eman Alharbi
1401111
A Few Rules from "A
Handbook for Scholars
Saja Alqurashi
1305553
Notes on Technical Writing
Suzan Almotairi
1401104
Toward Clarity and Grace
2
Style: Toward Clarity and Grace
Principles of Clear Writing
In order to avoid writing sentences that feel gummy, lumpy, abstract, we
have to follow these steps:

Use subjects to name characters. (Characters as subjects)
 Given a sentence we should be clear with the characters involved

Express crucial actions in verbs (actions as verbs)

Write sentences with about five or six words. For long sentences, find out the
subject and try to split the sentence.

Without named characters and turning verbs into nouns:
 Example: There has been an affirmative decision for program termination

Using subjects to name characters and name their actions:
 Example: The Director decided to terminate the program.
Stylistic Consequences
Advices for clear writing:

Write short and direct sentences.

Avoid using too many prepositional phrases. Using verbs instead of abstract
nouns.
 Example: An evaluation of the program by us will allow greater efficiency
in service to clients.
 Example (Better): We will evaluate the program so that we can serve
clients better.

Put your ideas in a logical order and use connectors to clarify logical
relationships.
 When you turn nouns into verbs, you have to use logical operators like
because, although, and if to link the new sequences of clauses.
Continued




If the subject is implicit but clear, the sentence need not be rephrased.
Example:
 This evidence proves my theory.
 With this evidence, I prove my theory
If a character is specific in the adjective, its good to revise.
 Determination of policy occurs at the presidential level.
 Better: The President determines policy.
Change objects of prepositions and abstract nouns like:
 That the instability of government was a consequence of popular
democracy.
 Better: That popular democracy destabilized government.
Most writers use verb not to express action but to state that an action exists
(like possibility) is removed in the second sentence.
 There is the possibility of prior approval of it.
 Better: He may approve it ahead of time.
Continued



Express actions and conditions in specific verbs, adverbs, or adjectives.
The sentence should be clear, direct, and readable.
Verbs and Actions will cover not only physical movement, but also mental
processes, feelings, relationships, literal or figurative. In these examples, the
important verbs are control and disseminate; while be and exercise are not
crucial verbs.
 There has been effective staff information dissemination control on the
part of the Secretary.
 The Secretary has exercised effective staff information dissemination
control.
 The Secretary has effectively controlled staff information dissemination.
 The Secretary has effectively controlled how his staff disseminates
information.
Continued

Nominalization is itself a noun derived from a verb or an
adjective. For Example:

Some nominalizations do not change: hope, charge, result,
answer, repair, return, etc.
To avoid abstract nominalizations, you can make your style more
direct and also avoid unnecessary passive verbs.


Nominalization follows a verb: change the nominalization to a verb that can
replace the empty verb.
 The police conducted an investigation into the matter.
 Better: The police investigated the matter.
Continued



Nominalization follows there is or there are: change nominalization into verb
and find the subject.
 There is a need for further study of this program.
 Better: The engineering staff must study this program further.
Nominalization is a subject of empty verb: change nominalization into verb
and find new subject.
 The intention of the IRS is to audit the records of the program.
 Better: The IRS intends to audit the records of the program.
Consecutive nominalizations: change first into verb. The next could be left as
it is or changed into verb in a clause beginning how or why.
 There was first a review of the evolution of the dorsal fin.
 First, she reviewed the evolution of the dorsal fin.
 Better: First, she reviewed how the dorsal fin evolved.
Continued

Nominalization in a subject is linked to nominalization in the
predicate by a verb or a phrase: change abstractions to verbs, find
the subject, link with a word that expresses logical connection.
 Example: Their cessation of hostilities was because of their
personnel losses.
 Words for logical connection:
 To express simple cause: because, since, when
 To express conditional cause: if, provided that, so long as
 To contradict expected cause: though, although, unless
 Example (Better): They ceased hostilities because they lost
personnel
Continued

Useful Nominalizations
 Subject referring to a previous sentence
This decision can lead to costly consequences.
 Names what would be object of its verb
 I do not understand either her meaning or his intention.
 I do not understand either what she means or what he
intends.
 Refer to an often repeated concept. If something is referred
open in the text, we could shorten it using normalization.
 Some ideas can only be referred in nominalizations: freedom,
death, love, hope, life, wisdom, etc.
Continued



To choose between passive and active: answer two questions
 First, must our audience know who is performing the action?
 Second, are we maintaining a logically consistent string of
subjects?
Scholars in different fields write in different ways.
To expect to write everything in passive and third-person form is
wrong.
A Few Rules from
"A Handbook for Scholars"
How to do citation
1.
2.
3.
4.
5.
Indicating the name of the author or not depends on the impact
of indicating the name.
If you cite a paper with more than two or three authors you
should use "et al."
The sentence should still be correct if you keep the braced
number or leave it out.
Don’t tell your reader to "see" (or "refer to") a source.
To cite your own work, extra words are required to clarify the
case. Indicate that the work was done by you using “I”


E.g. (bad):This problem was studied earlier, but in a less general setting
[2,3,5].
(Good):I studied this problem earlier [2,3,6], but in a less general setting.
General Advices For Writing
1. You can use we in the sentence if you are writing a paper with
one or more co-authors.


If you are the sole author of the paper then use I instead of we or our.
If you want to avoid using "I" you can do so by reformulating the sentence.
2. Use obviously or we observe, only when the statements are
crystal clear.
3. Try not to use footnotes. Otherwise, don't put important
information in a footnote.



Sentence should make sense even without the footnote.
Punctuation should follow Footnote symbol and not vice versa.
Don’t use the footnote symbol for other purpose.
General Advices For Writing
4. Use "As" to link the whole clause to the rest of the sentence and
"like" links a noun or pronoun.




(bad):The students thought that the professor was acting as a child.
(good): The students thought that the professor was acting like a child.
(bad): The students thought that the professor was acting like a child does.
(good): The students thought that the professor was acting as a child does.
5. "If it were" is used for conditions contrary to fact, whereas "if it
was" is used for simple conditions.
 If the polygon were simple (but it is not) we could apply the standard
techniques, but now we have to come up with something clever
6. In doubt, use “may”. If you are sure, use “can”

This example is bad as you are sure of the proof: The reader may find the
proof of this lemma in Appendix A.
Continued
7. Capitalization: Don't use too many capitals; Articles are
capitalized at the beginning of sentences, sentence quotations, and
titles
8. Coherence: Add the connectives (hence, thus, so, therefore)
between sentences only where emphasis is needed.
9. Summarize: If you cannot find a good reason to give an overview
or to summarize, then don't. Starting a section stating “In this
section we show …” is useless.
17
Continued
10. “Let us”: don't use "let us" as a more formal variant of "let's" .


Example: Let us distinguish the case where pi > 0 and the case where pi
<= 0.
You can either use "Let's" or, if you find that too informal, rephrase the
sentence.
11. Avoid Latin expressions and abbreviations of Latin expressions
as much as possible.



Use “for example“ instead of “e.g.”
Use “that is” instead of “i.e.”.
Avoid using “etc.”
Continued
12. Whenever writing about any list of items, write a separate
paragraph for each item in the list.
13. "Respectively" is used to link members of one set to members of
another.


Example: Spiders, humans, and whales have eight, two, and zero legs
respectively.
Example (Better): Spiders have eight legs, humans have two, and whales
have none.
14. "That" is used in a restrictive clause. A restrictive clause is
essential, it cannot be deleted from the sentence; "Which" is used in a
non-restrictive clause, one that can be deleted. You should put a
comma before and after the non-restrictive clause
Mathematical Writing - Knuth
(Optional to read)
Notes on Technical Writing



Symbols in different formulas must be separated by
words.
 Bad: Consider Sq, q < p.
 Good: Consider Sq, where q < p.
Don’t start a sentence with a symbol.
n
 Bad: x − a has n distinct zeroes.
n
 Good: The polynomial x − a has n distinct zeroes.
Don’t use the symbols . . . ; replace them
by the corresponding words.
 (Except in works on logic, of course.)
Continued



The statement just preceding a theorem, algorithm, etc.,
should be a complete sentence or should end with a
colon.
Bad: We now have the following
Theorem. H(x) is continuous.
Good: We can now prove the following result.
Theorem. The function H(x) defined in (5) is
continuous.
Continued




The statement of a theorem should usually be selfcontained, not depending on the assumptions in the
preceding text.
The word “we” is often useful to avoid passive voice;
“we” might mean the author and the reader.
There is a definite rhythm (definition) in sentences.
Read what you have written, and change the wording if
it does not flow smoothly.
5 Tips About Writing with Rhythm. View
Continued

Don’t omit “that” when it helps the reader to parse the
sentence.






Bad: Assume A is a group.
Good: Assume that A is a group.
Bad: “We have that x = y”
Good: “We have x = y”
Vary the sentence structure and the choice of words, to
avoid monotony. But use parallelism when parallel
concepts are being discussed
Don’t use the style of homework papers, in which a
sequence of formulas is merely listed. Tie the concepts
together with a running commentary.
Continued

Try to state things twice, in complementary ways,
especially when giving a definition.

Motivate the reader for what follows.

Many readers will skim over formulas on their first
reading of your exposition. Your sentences should flow
smoothly when all but the simplest formulas are
replaced by “blah” or some other grunting noise.
Blah means refer to something that is boring or without
meaningful content.

Continued



Don’t use the same notation for two different things.
Conversely, use consistent notation for the same thing
when it appears in several places.
Don’t get carried away by subscripts, especially when
dealing with a set that doesn’t need to be indexed; set
element notation can be used to avoid subscripted
subscripts.
Display important formulas on a line by themselves. If
you need to refer to some of these formulas from remote
parts of the text, give reference numbers to all of the
most important ones, even if they aren’t referenced.
Continued


Sentences should be readable from left to right without
ambiguity.
Small numbers should be spelled out when used as
adjectives, but not when used as names (i.e., when
talking about numbers as numbers).
Continued





Capitalize names like Theorem 1, Lemma 2, Algorithm 3, Method 4.
Some handy maxims
 Watch out for prepositions that sentences end with.
 When dangling, consider your participles.
 About them sentence fragments.
 Make each pronoun agree with their antecedent.
 Don’t use commas, which aren’t necessary.
 Try to never split infinitives.
Some words are frequently misspelled by computer scientists
For Example :
implement not impliment; complement not compliment; occurrence not
occurrence; dependent not dependant; auxiliary not auxillary; feasible not
feasable; preceding not preceeding; referring not refering; category not
category; consistent not consistant; PL/I not PL/1; descendant (noun) not
descendent; its (belonging to it) not it’s (it is)
Continued


The following words are no longer being hyphenated in current
literature: nonnegative, nonzero
Don’t say “which” when “that” sounds better. The general rule
nowadays is to use “which” only when it is preceded by a comma
or by a preposition, or when it is used interrogatively.
 Bad: Don’t use commas which aren’t necessary.
 Good: Don’t use commas that aren’t necessary.
Continued




Does not use any special punctuation.
For Example: “nonincreasing” vectors:
n
 An = {(a1, . . . , an)  N | a1 · · · an} . (1)
If C and P are subsets of Nn, let:
 L(C, P) = . . .
and those colons are wrong.
Continued

The opening paragraph should be your best paragraph, and its
first sentence should be your best sentence.
 Bad: An important method for internal sorting is quick sort.
 Good: Quicksort is an important method for internal sorting,
because . . .
 Bad: A commonly used data structure is the priority queue.
 Good: Priority queues are significant components of the data
structures needed for many different applications.
For Extra information:
Visit: Strong body paragraph.
Continued

The normal style rules for English say that commas and periods
should be placed inside quotation marks, but other punctuation
(like colons, semicolons, question marks, exclamation marks)
stay outside the quotation marks unless they are part of the
quotation.
 Good: Always end your program with the word “end”.
 Bad: This is bad, (although intentionally so.)
For Extra information: Sentence Punctuation Patterns
Continued


Resist the temptation to use long strings of nouns as adjectives:
consider the packet switched data communication network
protocol problem.
In general, don’t use jargon unnecessarily. Even specialists in a
field get more pleasure from papers that use a non specialist’s
vocabulary.
References








An excerpt from style: toward clarity and grace [Part One] , by Joseph M.
Williams
An excerpt from style: toward clarity and grace [Part Two] , by Joseph M.
Williams
A Few Rules from "A Handbook for Scholars" Retrieved from:
http://www.iris.ethz.ch/msrl/lectures/iris_studies/scholars.php
Notes on Technical Writing.
http://grammar.about.com/od/rs/g/rhythmterm.htm
http://www.dailywritingtips.com/5-tips-about-writing-with-rhythm/
https://depts.washington.edu/owrc/Handouts/Strong%20Body%20Paragraphs.
pdf
https://owl.english.purdue.edu/owl/resource/604/01/