Writing Guidelines

Some of you are taking this course to fulfill the Engineering Communication Requirement, while others of you (particularly those outside of the School of Engineering) are not. Either way, we hold everyone to the same standard regarding documentation. This is an interdisciplinary course, and you must write documents that are clear, concise, and easy-to-read by all of the members of your group. In grading your documents we are not only be looking at what you say, but how you say it.

The key concept is writing documents that are skimmable. Readers should be able to look at the document quickly and get the basic ideas. They can then decide whether to read the document more thoroughly to get the details. This applies to everything from a high-level concept document to a detailed architecture specification.

Proper formatting is essential for achieving skimmability. Every formatting choice, from font size and style to bullet-points to tables and figures makes a big difference in how a document is received. The purpose of these guidelines is to help everyone to understand how to use these properly to aid understanding.

[Sections]   [Paragraphs]   [Bullets]   [Figures]   [Tables]   [Punctuation]   [Gender]

Sections

Any document should be broken up into sections. A section is a logical unit of material that is reasonably self-contained. Ideally, readers should be able to see a section in detail while skimming over the other sections. If material between two sections is so tightly coupled that it is impossible to understand one without the other, this is typically a hint that the presentation needs to be reorganized.

Any section can be broken down into further units known as subsections. Indeed, writers can use subsubsections, subsubsubsections, and so on. As with sections, the purpose of subsections is to present the material so that the readers can focus on some elements of the section and skim over others. There are no hard rules on nesting subsections, though it is very rare for a document to require more than subsubsubsections. For example, HTML only supports six levels of headings, and the last two heading levels are almost never used.

Headings

One of the most important parts of formatting a section is the heading. A heading serves as a title for the entire section. It is text that is larger than the normal text size and appears at the start of the section. For example, Section was the heading for the current section, and Headings was the start of the current subsection. Headings are typically nouns or noun phrases indicating the primary topic of the text in that section.

Note that section headings get smaller in size moving from section to subsection. This is the primary way to tell the headings apart. If readers want to skip an entire section, they can skim until finding a heading of the same size. The following is a good advice for sizing headings:

• The top-level section heading is 200% the size of normal text
• The subsection heading is 150% the size of normal text
• The subsubsection heading is 125% the size of normal text
• Further subsections are the same size as normal text, but highlighted differently.

Highlighting refers to any design element used (other than size) to make the heading stand out. Typically, this means bolding the text. However, document designers can highlight with italics, color, or choice of a different font. The way that teams design or highlight can be highly variable, but the document must be consistent in its approach. All subsections at the same level should be highlighted the same way.

Headers are traditionally centered or flushed to the left, to line up with the text. While there are many options, the standard preference is to only apply centering (if at all) to the top section headers, and align all subsection headers to the left.

Web pages often have horizontal lines before a new section. Teams can do this in a written document, but it is not necessary. Web pages need it because the document does not break up into individual pages. Page breaks serve the same role as these horizontal lines in a written document. With that said, if teams think a horizontal line looks good, they are free to use such.

Organizing Content

Teams can organize content within sections as they see fit, but always keep in mind the following rule: the most important information should always be closest to the header. The first sentence of a section (or subsection) is the most important (remember topic sentences?). The first paragraph is more important than the second. As a section goes on without a new header, the information should become less and less important.

While drafting, if writers find important information is surfacing later on in a section, and there is no easy way to reorganize the material, that means it is is time for a subsection. The new heading will draw the eye and indicate that to readers that they should start paying attention again. Use subsections carefully and judiciously. If there are too many of them, the readers will start to ignore them, which defeats the purpose.

Pitfalls: Indentation

In the past, we have found that students like to indent subsections, to make them stand out more. If the headings are formatted properly, this is unnecessary (all it does is make the documents look ugly). Furthermore, it makes it difficult to insert tables or figures into deeply nested subsections. Do not do this.

Pitfalls: Widows

A widow is a section header with no paragraph underneath it (because it got moved to the next page). This is a high crime of technical writing. If were a Cornell graduate student submitting your thesis or dissertation, it is one of two issues (the other being orphans) that would result in immediate rejection of your manuscript. Likewise, widows are unacceptable in this course.

Paragraphs

Inside each section, most of of the information should be organized in paragraphs. Information in a paragraph should always be presented in complete sentences. Incomplete sentences are only appropriate for bullet points, and bullets should be used sparingly.

The paragraph topic should be apparent in either the first or second sentence. The initial sentences in a paragraph act just like a section header; readers should be able to look at them and determine whether or not it is worth reading that paragraph.

Paragraphs should always be long enough to convey the information at hand and no more. While there are no explicit rules for the length of a paragraph, one-fifth of a page is a good target. Any more than that and the paragraph risks becoming a "wall of text" that is impossible to skim. If paragraphs become too long, consider breaking them into more than one paragraph. Check in with the ENGRC instructor if you are feeling unsure.

Topic Paragraphs

For many of the documents in this class, teams will be writing a series of related paragraphs. For example, in the Concept Document teams have to identify several competitors and describe each of them. There is a modern tendency to format these lists as bullet points (we blame Wikipedia). This is unacceptable; bullet points should never be more than one or two lines. You should use a topic paragraph instead.

A topic paragraph begins with a topic, which is typically a noun or noun phrase indicating the topic of the paragraph. This topic is highlighted just like a section header, except that it is part of the paragraph (e.g. not a on separate line) and is the same size of the rest of the text).

The topic is followed by a separator. This is some form of punctuation that separates it from the rest of the paragraph. Many times this is a colon, but it can also be a period or dash. There is no restriction here as long as you are consistent among all the topic paragraphs. After the separator, you write the rest of the paragraph as normal.

Sometimes writers like to make a clearer separation between topic paragraphs and normal paragraphs. Unlike sections, writers are permitted to indent topic paragraphs, though this is not required. Only indent a topic paragraph if a section mixes normal and topic paragraphs. If a section is comprised of nothing but topic paragraphs, then do not indent them.

Putting all this together, the following is an example of a topic paragraph:

Example Paragraph: This paragraph is an example of a topic paragraph. Note the bolded topic at the beginning, followed by the separator. This topic paragraph also makes use of (optional) indentation, because it is preceded and followed by normal (non-topic) paragraphs.

A topic paragraph is essentially a type of subsection. The big difference is that it is limited to a single paragraph and the heading is included within the paragraph. If writers find a need to break a paragraph up into more than one paragraph, this is a hint to use a subsection instead.

Pitfalls: Orphans

An orphan is when a new page of the document starts with the last line of a paragraph from the previous page. Like widows, Cornell would reject a graduate dissertation or thesis with this type of error. In this course we have an even broader definition of orphan; we also count the case in which the first line of a paragraph is by itself on a page. As a result, this course has the following rule for multi-page paragraphs: for a paragraph that spans more than one page, at least two lines of the paragraph must be on each page.

Obeying this rule is trickier than it might seem. The rule means that if there is a three-line paragraph, it must all fit on a single page. Furthermore, when eliminating an orphan by moving the paragraph to one page, writers might accidentally create a widow. A section header followed by a three-line paragraph is the worst, as writers may have to move everything to the next page, creating a lot of empty space in the process. When this happens, think about editing and/or reorganizing the document to prevent this problem.

Bullets

Bullet points are one of the most abused writing elements. Bullet points are intended for one thing and one thing only: concise lists of related information that are to be viewed "simultaneously." For example, the feature list in the Concept Document is an excellent candidate for bullet points. The producer wants a quick summary of the major features of the game, and wants to see them all at once.

This means that bullet points must be short; they should never be more than one or two lines each. The should never be more than one of two sentences. Most importantly, bullet points should all fit on a single page. If the reader has to flip between pages to view everything in the list, this defeats the purpose of the bullet points.

As technical writers, be aware that bullet points are equalizers; if you use bullets, all items are equally important. Any hierarchy or ordering that is assumed is false. (If teams needs order or hierarchies, use numbered lists instead.)

If you find it hard to meet the space constraints for bullet points, you should use topic paragraphs instead. Furthermore, do not put bullets beside the topic paragraphs; the topic formatting style is enough.

Pitfalls: Consistency

Bullets points do not have to be complete sentences. However, if the bullet points are not complete sentences, then everything in the list must be the same part of speech. You should not have a list of bullet points that mixes noun phrases with verb phrases, or sentences with incomplete sentences.

For example, consider the following list of bullets outlining challenges in a game.

• Ninjas
• Zombies
• Avoid spike traps

This is a bad bullet list; the first two bullet points are nouns, while the last bullet point is a verb phrase. Rewording this as Avoiding spike traps is better, because it is now the same part of speech as the other two bullets (a gerund is a noun phrase).

However, that choice of wording is still inconsistent with the other two bullets. The first two bullets describe the actual hazards themselves, while the last bullet describes how the player should react to the hazard. The hazards should all be described in the same way. Hence the best wording for this bullet is Spike Traps. This type of consistency is much harder to achieve than ensuring the bullets are all the same part of speech. It will only come through practice.

Figures

A figure is a picture embedded in the document. Player mode diagrams and level-design storyboards are the major examples of figures in this class. Figures can be digital creations or scanned from a piece of paper. Except for the game manual, we will never grade a document on the artistic quality of its figures.

Figures should always fit within the margins of your document. If the figure exceeds the margins, you should reduce the figure in size. This includes both the horizontal margins and the vertical margins.

Most figures should be centered horizontally with no text on the left or right side. However, if the figure is small enough, you can put text to one side. If you do this, you should provide ample space between the text and the figure (at least a quarter of an inch). Furthermore, neither the text nor the figure should be less than a quarter of the width of the page.

Captions

A caption is text that appears below a figure, describing its contents. Captions are usually a good idea, as they help with skimability. However, it may be safe to omit a caption when the image is self-contained, such as an activity diagram in an Architecture Specification. We will advise you about this on a document-by-document case.

Captions should have three elements: label, title, caption. The label is was to refer to the image, like Figure 1 or Player Mode 3. Sometimes, for reasons of space, a figure has to be moved far away from the text that refers to it, such as on the next page. When you refer to the figure, you should use the label.

The title is like a header; it is a fragment that names the thing itself, like Navigating Level 1. You do not need to refer to the title when referring to a caption, but the title should be clearly highlighted with bolding.

Finally, the caption itself is a collection of short full sentences that explain or interpret the figure itself. It should be enough to put the information in context, but should not be multiple paragraphs or excessively long. The preferred highlighting of a caption is italics, to clearly distinguish it from the main body of the text. See this document for examples of captions in technical documents.

Captions should either be left-justified or centered. A caption should not be centered if it takes up more than one line. If the caption is left-justified, it should align with the left-border of the image (which is not necessarily the same as the left margin).

Multiple Figures

Team writers can put multiple figures adjacent to each other horizontally. This is particularly useful with level-design storyboards. When arranging figures side-by-side, follow the same rule as text as figures. That is, be sure that there is sufficient space space between the figures and no figure should be less than a quarter of the width of the page.

Figures that are arranged side-by-side do not have to be the same width, but should be the same height. There are acceptable layouts that break this rule, such as a large picture adjacent to two smaller pictures on top of each other. However, this type of arrangement is getting into questions of graphic design that is beyond the scope of the course. The most important rule is that the all of the adjacent figures should have align so that there is an implicit bounding box about them.

Tables

In the case of placement and captions, tables generally follow the same rules as figures. The primary exception is that a table can span multiple pages. This should be avoided if at all possible; sometimes it is better to move the table to later in the document and rely on the caption to put it in context. However, if a table is more than a single page by itself, it will have to be split up.

If a table is split across multiple pages, put the table header on each page. The table header is the first row of the table and it indicates the topic of each column. The contents of the table header should be highlighted in some way, either with bold, italics, color, or font choice.

Tables should also have captions, as following the same rules for figures explained above.

Pitfalls: Sizing

Do not shrink the text inside of a table to make it fit within the margins of the page. The text in the table should be approximately the same size as the text in the rest of the document. If the table is too wide for the document, the best solution is to make the columns narrower. The may result in the text in each cell spilling over multiple lines. This is acceptable.

With that said, tables are like bullet points in that they are intended to contain concise information. If the table cells contain five or more lines of text, think about pulling the information out of the table and putting it a topic paragraph below the table. Indeed, a great way to use a table is to fill the cells with short topics or descriptions, and then use topic paragraphs to expand on the meaning of these.

Example:

The following combination shows off how to combine tables and topic paragraphs to present information in a way that is concise and easy to follow.

Table 1: Unit Abilities.

Unit	Abilities
Warrior	Melee, Range
Shaman	Range, Healing

Melee: Units with the melee ability can only attack units that are in a square adjacent to them (including diagonals). Melee attacks do significant damage to make up for their limited reach.

Range: Units with the range ability can attack any unit that is within an unobstructed line-of-sight. If there are any units, even friendly ones, in-between this line-of-sight, then the unit cannot attack.

Pitfalls: Consistency

Each table column must obey the same consistency rules that bullets do. That means that all of the text in the each column must be the same part of speech. When describing a feature like a game hazard, all of the entries in the column should describe them in the same way.

These rules do not apply across table columns. It is perfectly acceptable for one column to consist of only noun phrases while another column consists of only verb phrases.

Punctuation and Quote Marks

In this course, we will us US-based English punctuation rules. This particularly affects data formatting and number separators.

In the US, it is proper to use double quote marks. There is only one time that single quote marks are acceptable: a quote within a quote. You will not be using such a format in this course, so there is no reason to use single quote marks. You can be comforted in knowing that anytime you see single quote marks, they are incorrect for US usage.

If your quote marks fall at the end of the sentence, the end punctuation (usually a period) goes inside the quote marks. This is a unique tradition to US English.

Gender-Neutral Language

This course, and all of Cornell and likely all future employers, will not allow biased language. Biased language includes deploying the universal male (wherein words like "he" and "his" and "man" are meant to mean "everyone"). Doing so breaks school code, most corporate styles, and is not desirable for legal purposes.

Instead, you should use language that does not draw attention to itself by making mistakes. The easiest and most unobtrusive way to avoid the issue is to use the plural. It is just as easy to write "Players will enjoy their games" as it is to write "The player will enjoy his game."