Basic Structure for Reports
Last updated by Norman Fenton on 31 July, 2001
Although these pages are primarily about improving the content of your writing (by understanding principles of good style) it is important that you first learn what is the required structure of a technical document. Thus, this section describes the syntax of technical writing, as opposed to its semantics. Take careful note of this section: there is never any excuse to get the syntax wrong.
What every report should contain
Sections and section numbering
Return To Norman Fenton's home page
What every report should contain
Make sure every report contains the following basic information:
Title
Author name(s), affiliation and contact details
Date
Version number
Abstract (if more than 5 pages - click here for how to write good abstracts)
Page numbers
Table of contents (if more than 10 pages)
Conclusions (if more than 5 pages)
It is incredible how many reports I receive that fail to contain this basic information (students, for example, often fail to put their name on their reports).
The first five items above must appear on the front page.
Ideally, each page should have a header and a footer (in MS Word you create headers and footers from the View menu). The header should contain the author, title, and version number. The footer should contain the date and page number.
Page numbers should appear preferably in the form "Page n/m" where m is total number of pages. In Word it is easy to generate the number corresponding to total number of pages automatically - just insert the field "NUMPAGES" (click on Insert/Field menu and then just click on the NUMPAGES).
Any report that is subject to a review procedure should also contain a 'change history' page, where the version numbers and dates are listed with the main changes that were made.
Sections and section numbering
Any report longer than 3 pages (in other words, anything other than a memo) should be broken up into sections using the following principles:
- Sections should be numbered (preferably using Roman numerals. 1, 2, 3, ..). Whatever numbering convention you use you must be consistent.
- Each section should have a proper heading which accurately reflects the material contained within it.
- Long sections should be broken up into subsections which should be numbered n.1, n.2, etc where n is the section number.
- Long subsections should be broken up into subsubsections which should be numbered n.m.1, n.m.2, etc where n is the section number, m is the subsection number.
- No numbered decomposition smaller than subsubsection should be considered. Use bullet points, itemized lists, numbered lists, numbered examples, etc instead.
In what follows we will use the word component as the general term for a section, subsection or subsubsection. Thus, components are the building blocks of the document.
There are no hard and fast rules about ‘how long’ a component should be. It is more important that each numbered component contains a coherent content that is accurately summarised by its heading. However, in each document, component lengths at the same level should not be drastically different. For example, a document of 20 pages that contains 3 sections, one of 18 pages and the others with one page each, is an indication of poorly structured thinking.
At every level of decomposition there must always be AT LEAST TWO components. Thus, for example, a section can contain either no subsections or at least two subsections, but must never contain a solitary subsection. So the following structure is NOT allowed:
1. Part One
2. Part Two
2. 1 Part TwoPointOne
3. Part Three
(Here Section 2.1 is called a ‘hanging’ subsection.. There must never be hanging components like this)
However, the following is OK:
1. Part One
2. Part Two
2.1 Part TwoPointOne
2.2 Part TwoPointTwo
3. Part Three
(It is perfectly acceptable to have some sections without any subsections)
The crucial role of 'introductions'
The following rules explain the nature of ‘Introductions’ at different levels of decomposition:
At the section level, the first section should be an introduction and overview of the entire report. It should end by giving a walkthrough of the subsequent sections.
Where a section is broken into subsections the text immediately before the first subsection should be an introduction and overview of the entire section. It should end by giving a walkthrough of the subsequent subsections.
Where a subsection is broken into subsubsections the text immediately before first subsubsection should be an introduction and overview of the entire subsection. It should end by giving a walkthrough of the subsequent subsubsections.
In other words, at each level of decomposition, preceding the first main component at that level, there should be an introduction and overview of the set of components at that level. This introductory text should say what is contained in each of the components. Thus:
1. Section One (Introduction)
This is the introduction to the entire report. This report is about blah blah blah.
This report contains two main sections. Section 2 covers …. Section 3 covers …..
2. First main section
Since this section is broken into two subsections, the text here should just state what the purpose of this section is and what is covered in Section 2.1 and Section 2.2
2.1 Section TwoPointOne
The text for section 2.1 goes here
2.2 Section TwoPointTwo
Since this subsection is broken into two subsubsections, the text here should just state what the purpose of this subsection is and what is covered in Section 2.2.1 and Section 2.2.2
2.2.1 Section TwoPointTwoPointOne
The text for section 2.2.1 goes here
2.2.2 Section TwoPointTwoPointTwo
The text for section 2.2.2 goes here
Section Three
The text for section 3 goes here.
- Every figure and table in your document should be numbered and labelled, as in Figure 1.
Figure 1: A very fine footballer
- Every reference to a figure or table should use the number of the figure or table. Thus, never write something like "the figure below shows a footballer", but write "Figure 1 shows a footballer". Spatial references to figures without numbering are nearly always ambiguous. Moreover, when you reformat your document you may find that the figure that was once 'below' actually appears on the top of the next page.
- Every figure or table which appears in the document must be cited at some point in the document (this is a consistency requirement).
Return Norman Fenton Home Page
A Structure for Student Project Reports
The following is an indication of the kind of structure that should be used in the write-up of a student project. In this example I will assume the project is about building a Bayesian network tool for predicting software faults.
Abstract (see How to write good abstracts) less that one page
Table of Contents
Chapter 1. Introduction (see the crucial role of introductions)
Chapter 2. Background/motivation. Should set out the context for the work - why the chosen topic is important/interesting. In the example this would address the issues of why people are interested in predicting software faults and why a Bayesian network approach might be useful. This chapter could also provide an overview of previous work in software fault prediction and why it is lacking.
Chapter 3. Research. This chapter should describe your own research into the topics (if it covers more than one key topic then there should be a chapter for each), with full references. In the example, there are actually two topics you would need to investigate: software fault prediction and Bayesian networks, but the former could go in Chapter 2. For Bayesian networks you would be expected to provide an overview of what they are, how they are used, the tools that support them, and other similar BN applications.
Chapter 4. Requirements. This chapter should describe the requirements for the system you have built, together with how the requirements were captured. You should use UML notation of use cases.
Chapter 5. Design. This chapter should describe the high-level design of the system, preferably using class diagrams.
Chapter 6. Implementation. This chapter should provide an overview of the implementation, providing information about low-level design decisions not covered in the previous chapter. You should include screen shots. You should not include the full source code, but you should include code fragments that illustrate key points about your implementation.
Chapter 7 Testing. Describe what your test plans were and how you carried them out. At the very least you should explain how you tested against the use cases.
Chapter 8 Conclusions and recommendations: include the personal stuff (what you have learnt, what was good/bad, what worked/didn't, what you would do differently next time etc) and general recommendations (in the example this would be about building BN applications and software fault prediction)
References
Appendices (Log of meeting, work plan, detailed class
diagrams etc)
Return Norman Fenton Home Page