Document Design & Communication

Page Contents

  1. Communication: Writing and English Grammar
    1. Concise Writing
    2. Tips to Avoid Common Mistakes
    3. Commonly-Confused Words
  2. Document Design
    1. Layout
    2. Organization
    3. Headings
    4. Lists
    5. Visuals

Communication: Writing and English Grammar

Good writing skills can be an asset to everyone, regardless of your chosen profession. Computer scientists, physicians, and history teachers alike will find it advantageous to have the ability to communicate well through a written medium. Computer science is a discipline in which, like in many others, the ability to communicate is a necessity.

Part of being able to write well includes a practical understanding of basic English grammar. We cannot teach you English grammar in this 15-week course; however, we can provide some basic information regarding grammar and document design, as well as give you some tips to help you avoid some of the common mistakes that we often see.

Concise Writing

In technical documentation, you should strive to make your writing direct and concise. Your aim is to express yourself plainly and use few unnecessary words.

Writing concisely takes careful editing. Copyediting is the process of finding and correcting spelling, grammatical, or typographical errors. While this is a very important form of editing, it is also important that you edit your documents at a higher level for conciseness readability. Read through each paragraph and ask yourself, “Do each of these words work towards conveying the point I want to make?” Cut out extraneous information.

Tips to Avoid Common Mistakes

  1. Avoid vague generalizations. Broad statements without specific details are not needed in technical documentation. Your readers need specifics — so give it to them!
  2. Remember to explain technical terminology. Ask yourself, who is my audience? Do all my readers have a background in the problem domain and technologies discussed? If not, which terms need to be explained? Don’t assume that since you know it, your audience will.
  3. Acronyms can be used anywhere in a document once they are defined. You should define the acronym the first time it is used.
  4. Use spell checking and grammar tools built into your word processor, but please remember to re-read! All team members should help edit the document, especially for portions that they did not write. A good rule is, “Don’t edit your own on your own.”
  5. Use parentheses to enclose inline supplemental material and always place the period outside the parentheses.

    Correct:

    Test the functionality of menu selection for a system administrator (see Requirement 2.2.1).

    Incorrect:

    Test the functionality of menu selection for a system administrator. (see Requirement 2.2.1.)

Commonly-Confused Words

affect verb that means “to influence”
effect noun that means “result or consequence”
or
verb that means “to bring about”
its possesive form of the pronoun it
it’s contraction for it is
i.e abbreviation meaning “that is” or “put another way”
e.g. abbreviation meaning “for example”
their possisive form of the pronoun they
they’re contraction for they are
there adverb meaning “in or at that place or position”
than conjunction used in comparisons
then adverb indicating time
who’s contraction for who is
whose possessive form of who
your possessive form of the pronoun you
you’re contraction for you are

Document Design

One of the most important things you should remember when designing documents is to keep your reader in mind at all times. You are creating your document for a particular reader or group of readers and should plan, write, and design with them in mind. Read through the design principles below and utilize these guidelines and tactics as you create the project documents for this course.

Layout

  • Use white space effectively and often.
  • Keep margins wide and spacing ample. Pages should have at least 1-inch margins.
  • All pages (except for the title page) should be numbered.
  • Though you are not required to start all document sections on a new page, it may be advantageous to do so in some cases to prevent widowed or orphaned text.

Organization

  • Use headings to divide long sections and categorize information.
  • Use bullets, numbers, and outlines, as appropriate.
  • Use headers, footers, and footnotes, when applicable.

Headings

As you can see by reading the guidelines for written reports, your documents will clearly be divided into sections and should, therefore, make use of headings. The purpose of a heading is to help readers see the organization of the document at a glance.

Most headings are left-justified on the page.

While headings are extremely helpful in helping readers locate needed information, use of more heading levels than necessary can make the document difficult to read.

If you use more than one level of headings (subheadings), you should use various formatting options to set these apart. Subheadings can be differentiated from higher-level headings by changing their font characteristics such as size, weight, or spacing.

Lists

As you write documents for this course, you may find that some information or material is not easy to convey in paragraph format. A bulleted or numbered list may be an efficient way to convey selected information since it is an easy format to read quickly. Additionally, the use of lists “breaks up” the page by creating white space, and makes the page, as a whole, easier to read.

Although the use of lists in a document is a positive design tool, too many lists in one document can make it hard to read; the document may start to appear disjointed. Make sure to keep a balance between listed information and narrative body text. Remember: lists are used to emphasize selected text.

Only use bullets that are appropriate for a given list (circles and dashes are most commonly used). Only use numbered lists when there is a need to number your text (e.g., for steps in a process).

Be sure to introduce your list before inserting it into the document. The example below uses an independent clause followed by a colon.

For this project, we will need the following resources:

  • Virtual Machine running Windows 10
  • Eclipse IDE
  • TomCat Server

When listing items in sentence or phrase format, try to put everything in parallel format. Parallelism is the repetition of a grammatical structure.

Visuals

You will be using a number of assorted visuals in the documents for this course, including tables, charts, graphs, GUIs, diagrams, flowcharts, and excerpts of code. The primary purpose of these visuals is to supplement the written text and support the various points contained therein. Keep in mind that many people are “visual learners” and that these visuals will aid your reader in understanding the written information that is conveyed in your body text. Additionally, these visuals have the potential to make your document more appealing and serve as another way to break up the text, create white space, and make the document easier to read.

One of the most common mistakes we see regarding the use of visuals in documents is in regards to placement. Since the primary purpose of your visuals is to support the text, visuals should be placed in the text of the document near the area to which it relates, or in an appendix that is referred to in the text.

Additionally, each visual should be numbered and labeled. Usually, figure numbers and captions are centered beneath the visual. The example below shows how visuals should be captioned (Fig. 1).

Waterfall MethodologyFigure 1 – Waterfall software development methodology