Formatting & Style Guidance

Throughout your time as a student you have written in various styles and formats. In CS 411W all writing will be Technical Writing in modified APA Format. There will be courses specific rules that supersede (more aptly, extend) both the rules of Technical Writing and APA Style.

1 No First Person

Take note of the first paragraph–ignoring the first sentence. Did you notice the lack of first and second person? All your writing in this course–with a few notable exceptions–will be in third person. This means no use of:

I
my
our
ours
we

in your Labs (i.e., Technical Papers).

2 No Contractions

Example 1: Mr Kennedy's Perspective

Have you ever wondered about my writing style–beyond some of my favored archaic grammatical constructs and somewhat obnoxious diction? Much of my style comes from CS 411W. Many of my habits come from when I was an undergrad in CS 411W. Most of my habits come from teaching CS 411W. A few quirks come from my code explanation emails (with which most are familiar).

My main quirk is my abhorrence of contractions. This include all the contractions we use in our daily lives:

I’ll

We’re

They’re

It’s

How’re

You’re

Of course, they’re and you’re are also homophones. It is difficult to fathom how so many people lackadaisically use:

they’re, their, and there

you’re and your

interchangeably.

3 Wrong Word

The most common mistake writers make is writing the wrong work. For a while I would write gambit instead of gamut. While the former–when capitalized–is my favourite non-Wolverine X-Men character, it (i.e., gambit) has an entirely different meaning.

Example 2: Mr. Kennedy's Perspective

One of the most common mistakes is except vs accept. Of course, I am a smart aleck. I like to talk about how one can effect a change in study habits–i.e., reduce Procrastinatory Lackadaisical Brinkmanship. My use here is perfectly correct.

Consider two sentences:

His shenanigans affected the group’s decision to order pizza.

and

His shenanigans effected the group’s decision to order pizza.

Both sentences are perfectly valid. However, the change of affected to effected fundamentally changes the meaning. In the first sentence someone’s tomfoolery (tomfoolery and shenanigans are synonyms) influenced the decision to order pizza. It was one part of a larger decision–maybe a small part.

The word effect (in the second sentence) changes the meaning. In this case, the tomfoolery was the fundamental factor in the group’s decision.

4 Too Many Words (Verbosity)

As Computer Scientists we tend to think more output is better. This follows directly from out use of debugging output–which should always be written to standard error. We must break this habit.

The most common example of wordiness is the phrase in order to. In general:

prefer “and” over “as well as”
prefer “to” over “in order to”

5 Should vs Must

If you have had Mr Kennedy before, you have definitely heard one of his lectures on should vs must. We will leave more detailed discussions as a topic of interest for another time…

6 Grammar

6.1 Latin Phrases

If you have had Mr Kennedy before, you have definitely heard one of his rants on i.e.,; e.g.,; alumni; or alumnus. We will leave Latin discussions as a topic of interest for another time…

6.2 Trailing Prepositions

Sentences should not end in prepositions. For example,

He forgot which test he was studying for

should be

He forgot for which test he was studying.

6.3 They, they, they…

Overuse of pronouns creates ambiguity. In cases were they is repeated in adjacent sentences, prefer the proper noun. If “they” can grammatically refer multiple things, prefer the actual nouns over a pronoun.

6.4 Domain Specific Proper Nouns

If you decide to treat your prototype, or a part of your prototype, as a proper noun, be consistent. Select a capitalization scheme with your team and “stick with it”.

7 Formatting Rules

All your writing must have 1-inch margins. Submit PDFs of your work. PDFs guarantee that formatting (e.g., margins) are not affected by how the document is viewed (unlike docx).

Make sure that your headings are all the same font face and font size as all other text. If you are using Word, LaTeX, Google Docs, or LibreOffice, do not rely on the default settings.

7.1 Figures & Tables

All Figures and Tables must have approriate numbered captions. All Figures and Tables must be referenced (using a cross-reference) before use, e.g.,

Vim (shown in Figure 1) can be used to write code in any language.

Never refer to a Figure or Table using relative position (e.g., above, below, to the left, to the right, on the next page).

7.2 Table of Contents & Listings

The Table of Contents must include every section heading and the correct page number.

A Listing of Figures and Listing of Tables must be included after the Table of Contents and list every figure and table, respectively.

7.3 Tables are not Figures

Even if you take a screenshot of a table (and insert it as an image) it is still a table.

8 Style Rules

There are various style rules in technical writing. Some rules are general. Some rules are organization specific.

8.1 Starting Sentences with Word Comma

Avoid starting sentences with:

First,
Firstly,
Finally,
In addition,
Additionally,
Also,

and other similar phrases.

8.2 App vs. Application

Spell out the word application; do not use app as an abbreviation.

9 Not Comprehensive

We are not done with this discussion. We will continue to revisit this document throughout the semester:

We will revisit existing sections.
We will add new sections.