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 involvedExpress 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 terminationUsing 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. Indicating the name of the author or not depends on the impact of indicating the name.

2. If you cite a paper with more than two or three authors you should use "et al."

3. The sentence should still be correct if you keep the braced number or leave it out.

4. Don’t tell your reader to "see" (or "refer to") a source.

5. 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 Writing1. 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 Writing4. 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. Bad: xn − a has n distinct zeroes. Good: The polynomial xn − 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 self-contained, 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:

An = {(a1, . . . , an) Nn | 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/