This document is intended to provide practical advise on writing guidelines
that I follow and that I look for in theses and projects. It is intended
to augment what you should already know. If you have difficulties with
organizing and writing your report you may want to consult the Writing
Resource Center on campus.
These guidelines are common errors of English that people make or
are personal biases (many of which were burned into my head by my
thesis advisor). This list has been compiled (and will continue to be
added to) based on comments I find myself making over and over again in
reading project reports and theses. If you have questions about these
guidelines please ask.
- The generic organization I look for in terms of chapters of the
report is as follows. Note these are only guidelines.
- Introduction
- What is the problem you are trying to solve? What is
the approach (your hypothesis) you are taking?
What is important about this work? Basically you want to motivate what you
are doing and why you are doing it.
Your Intro should conclude with a "roadmap" to the remainder of the
report. Something like "The remainder of the report is organized as
follows. In Chapter 2, we describe background and related work for the
project. Chapter 3 describes ... Chapter 7 concludes with a summary and
description of future work."
- Background
- Describe related work and background on the environment
you are doing your work in.
- Design
- What is the overall design of what you are doing. Why did
you take this approach. What alternatives did you consider?
- Implementation
- How did you implement the project? What issues came
up during the development of the project? Did you have to make any changes
in your design?
- System in Action
- An actual demonstration of the system in action
with examples is good if appropriate for your work.
- Results
- What are the results of your work? They can be
performance results or a subjective evaluation based on user feedback.
- Future Work
- Based on the results and your own evaluation what work
can be done in the future? This chapter is often included in the next
chapter.
- Conclusion
- What is important about your work? What summary
statements can you make? What did you learn in this project?
- The bibliography should contain an entry for each cited piece of work.
Each citation should contain four pieces of information if
available: title, author, date and venue (e.g. journal, conference, tech report,
news source). Other information such as URL, page numbers should also be
included if appropriate.
- Make sure you help the reader transition from one chapter to
another and from one section to another. A chapter should always start
with an introduction into the chapter (what you will talk about and how it
relates to what you just talked about). Similarly, the last section of
each chapter should be ``Summary'' and be a paragraph or two summary of
what the reader should take away from this chapter.
- Tables and figures are good additions to any report. A useful
writing methodology is to determine the set of tables and figures you plan
to use first then ``talk around'' them in your text.
- Each table and figure you use should have a caption. Captions for
tables always go above the table and captions for figures always go below
the figure. A simple rule to remember is ``table at top, figure at foot.''
- Each table and figure must be explicitly referenced by number in the
text. Thus do not say "as shown in the figure below", but say "as shown
in Figure 5" assuming that the figure is numbered 5.
- When refering to a specific chapter, section, figure or table, be
sure and capitalize the word. Instead of "as shown in section 3.1", you
should have "as shown in Section 3.1."
- The possessive form of the word ``it'' is ``its,'' not ``it's.'' The
use of ``it's'' is the contractive form of ``it is.''
-
Do not use contractions! Examples are ``didn't'' or ``it's.'' In
technical writing it is best to use the non-contractive form. Hence the
examples would be replaced by ``did not'' and ``it is.''
-
Avoid using the word ``very'' and other such words that try to embellish a
description. They do not add extra meaning and should be dropped. In the
words of my thesis advisor (and maybe his advisor and certainly Mark
Twain), ``replace the word
`very' with the word `damn' and reread the sentence, then get rid of the
`damn'.''
Bad example: The referenced article is very informative concerning this
topic.
Revised example: The referenced article is informative concerning this
topic.
- Re-check any sentence in which you repeat the same word more than
once. This situation is often an indication that one of the repeated words
can be dropped or the sentence should be rewritten.
Bad example: The large size of the network indicates the network may have
many problems.
Revised example: The large size of the network indicates it may have many
problems.
- Do not ``talk'' to the reader by using the word ``you'' or ``your,''
unless you are writing a document such as a user manual.
- Generally you should use either present or past tense in writing your
report. Particularly try to avoid using the word ``will'' unless you are
referring to an event in the future.
Bad example: After conducting the survey the next step will be to analyze
the results.
Revised example: After conducting the survey the next step is to analyze
the results.
- When you use the word ``this'' or ``these'' make sure you indicate
to what you are referring. This guideline reduces ambiguity in your
writing and helps tie sentences together.
Bad example: We found the performance results to be poor. This caused us
to revise our design.
Revised example: We found the performance results to be poor. These
results caused us to revise our design.
- Avoid using the word ``some'' and its variations whenever possible.
Many times the word is unnecessarily used and can be dropped. Its use
makes the writing weaker.
- The word ``data'' is plural (of ``datum''). Do not use the word
as a singular.
Bad example: This data indicates we were successful in our efforts.
Revised example: These data indicate we were successful in our efforts.
- Do not use the word ``thing'' or its variations. This word is vague
and has no meaning. Be specific when you write.
Bad example: The things we found with our testing were interesting.
Revised example: The results we found with our testing were interesting.
- Try to avoid ending sentences with words prepositions
such as ``to'' or ``of.''
Bad example: The second policy is what we refer to.
Revised example: We refer to the second policy.
- The use of ``that'' versus ``which'' is often confusing for writers.
To use an example that was drummed into my head consider the following two
sentences.
Example 1: I went to the store to buy a loaf of bread that was fresh.
Example 2: I went to the store to buy a loaf of bread, which was fresh.
Which one is correct? The answer is that either could be correct. The
word ``that'' is used when a qualifier is needed. Hence Example 1 would
be correct if the store had bread that was both fresh and not fresh. The
word ``which'' is used to reiterate a point. Hence Example 2 would be
correct if is was known that the store had only fresh bread.
- Punctuation (periods and commas) should be inside the quotes when
they are used
Bad example: Thus the decision was "politically correct".
Revised example: Thus the decision was "politically correct."
- Avoid gender-specific pronouns unless matched with a specific person.
Bad example: The user needs to change the xyz setting. This change allows
him to control the xyz level.
Revised example: The user needs to change the xyz setting. This change allows
the user to control the xyz level.
Alternate Revised example: The user needs to change the xyz setting, which
allows the xyz level to be controlled.