Report Do's and Don'ts by Prof. Craig E. Wills

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.

  1. 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?

  2. 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.

  3. 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.

  4. 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.''

  5. 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.

  6. 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."

  7. The possessive form of the word ``it'' is ``its,'' not ``it's.'' The use of ``it's'' is the contractive form of ``it is.''

  8. 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.''

  9. 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.

  10. 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.

  11. Do not ``talk'' to the reader by using the word ``you'' or ``your,'' unless you are writing a document such as a user manual.

  12. 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.

  13. 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.

  14. Do not use the word ``they'' to refer to a singular person. You can either rewrite the sentence to avoid needing such a reference or use the singular ``he or she.''

    
    Bad example: The user needs to set the environment variable FOO before
    executing the program.  If they do not perform this action, the program
    will fail.
    
    Revised example: The user needs to set the environment variable FOO before
    executing the program.  If he or she does not perform this action, the program
    will fail.
    
    Revised example: Users need to set the environment variable FOO before
    executing the program.  If they do not perform this action, the program
    will fail.

  15. 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.

  16. 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.

  17. 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.

  18. 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.

  19. 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.

  20. 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."

  21. 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.
    

Last Modified: Wed Mar 4 12:58:48 EST 2015