arranging_material_and_structuring_the_project_report [PATS2]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Arranging Material and Structuring the Project Report ======

You should consider, at the beginning of your project, what you need to do to solve the problem you have chosen to address. This will then inform choices about the structure of your reports; your written reports need to be both a "narrative" (telling the story of your project) and an "argument" (providing a logical justification of the steps you have undertaken to solve your chosen problem). Once you have started to gather material you can begin to arrange it in a form which can then be refined into a report, though the outline chapter headings shown below will serve as a good guide in the early stages of your work.

All good project reports whatever their subject, follow certain well-established conventions and have a similar overall shape. They generally consist of a main body surrounded by other information (presented in appropriate formats) that support it in various ways. Some of these are mandatory, others are optional. You can vary the titles of the sections if these are inappropriate for your project - your supervisor is the best person to guide you on this. Here we concentrate on the main body of the report and generic sections. We recommend for writing the report that you start with an outline of the main and sub-sections (or chapters and sections) as a guide on what you should be writing in detail.

We look at each of the general sections of the report structure in more detail below. You can use this characteristic structure as a rough template for organising the material. However, often it may be of advantage to adjust the suggested structure to your particular project instead of sticking to the template. Consult your supervisor for advice. It is also a good idea to plan roughly how long each part should be before writing the report, to make sure that the length and overall balance are about right. You can then construct each part to produce a first draft of the main body.

===== The "Introduction" =====

A good introduction should tell the reader what the project is about without assuming special knowledge and without introducing any specific material that might obscure the overview. It should anticipate and combine main points described in more detail in the rest of the project report. Also, importantly, it should enthuse the reader about the project, to encourage them to read the whole report. Normally it should include such things as:
  * the aim(s) or goal(s) of the project,
  * the intended audience or "beneficiaries" of the work done,
  * the scope of the project,
  * the approach used in carrying out the project,
  * assumptions on which the work is based and
  * a broad summary of important outcomes.

===== The "Background" =====

The purpose of the Background section is to provide the typical reader with information that they cannot be expected to know, but which they will need to know in order to fully understand and appreciate the rest of the report. It should explain why the project is addressing the problem described in the report, indicate an awareness of other work relevant to this problem and show clearly that the problem has not been solved by anyone else. This section may describe such things as:
  * the wider context of the project,
  * the problem that has been identified,
  * likely stakeholders within the problem area,
  * any theory associated with the problem area,
  * any constraints on the approach to be adopted,
  * existing solutions relevant to the problem area, and why these are unsuitable or insufficient in this particular case,
  * methods and tools that your solution may be based on or use to solve the problem,
  * and so on.

The wider context of the project includes such things as its non-computing aspects. So, for example, if you are producing software or any other products, including business recommendations, for a specific organisation then you should describe aspects of that organisation’s business that are relevant to the project. If you are doing a research oriented, say on particular algorithms, you should also refer to the general problem for which these algorithms are useful (the application(s) for your techniques).

Relevant existing products, documents or artefacts that you should mention could be ones that, for example,
  * are similar to the one you are proposing,
  * support your project,
  * your project aims to extend or replace,
  * demonstrate the "deficiencies" your project intends to address.

You need only describe things that will be unfamiliar to the potential reader, or are unique to the organisation or topic your project addresses. Your project, if it involves software development, will almost certainly use all kinds of existing software such as language compilers, subroutine libraries, etc., but you can assume that the reader will be fully acquainted with, for example, general purpose programming languages such as Java, C/C++, Fortran, Pascal, Python, PHP, etc,. Also, it may involve the better known specialised packages such as MySQL, ORACLE, OpenGL, etc. You should mention the particular variety and possibly version number, e.g. Java SE 6, but you need say nothing more than that.

If your project depends on any specialist or uncommon software such as specialised subroutine packages or a more obscure or specialised programming language, you should describe them briefly and discuss whatever features are relevant to your project. Often this can be done by comparing it to some well-established piece of software, for example
<code>
The Descartes language is like a restricted version of Pascal but with
the following extra features: ...
</code>

Again, long descriptions of details are to be avoided and references to suitable sources of detailed information should be given instead.

Other background information could consist of the sequence of events leading up to the present situation or the results of earlier investigations. You could also discuss such things as any cost or time constraints imposed on the project.

Your background section should end with a clear statement of the research questions problem your project is trying to answer. These will reflect the aim of your project, but will be different in that they explain the problem you are attempting to solve, e.g.,

**Example 1:**
<code>
Aim: 
The aim of this project is to develop software for the improved planning
of the routing of delivery vehicles to customer locations, that reflects
the forecast availability of each customer to receive goods.

Research question(s):
In order to demonstrate the achievement of the stated aim, this project 
will identify route planning software currently in use and the
underpinning algorithms, define appropriate performance metrics,
determine how to express constraints on an alternative algorithm, 
develop an improved algorithm and demonstrate on what basis it is judged
an improvement, and implement the improved algorithm in a usable and
robust software package.
</code>

**Example 2:**
<code>
Aim:
The aim of this project is to develop a business strategy for organisation
X that will improve the survivability of X in the face of increasing
global competition.

Research question(s):
In order to develop a business strategy it will be necessary to identify
key stakeholders and determine their vision for the organisation at the
end of the strategic planning time frame, assess the likely outcome, in
terms of the organisation's survivability, of maintaining the current
strategy, and develop and assess an alternative set of activities to
achieve the stated vision.
</code>

===== The "Specification, Design and Implementation" =====

This is one suggestion for the description of how your solution works. In some cases a methodology or approach to solve the problem may be more suitable to present the work. For this part, in particular, you have a lot of freedom of how to structure your report to present your solution.

==== Specification and Design ====

The purpose of specification and design is to give the reader a clear picture of the system you plan to create, in terms of the capability required. A specification should tell the reader what the software system is required to do. The design then gives the top-level details of how the software system meets the requirement. It will also identify constraints on the software solution, that are important in guiding decision making throughout the development process.
 
Describing what a software system does (specification) and how it does so (design) effectively usually means describing it from more than one viewpoint. Each viewpoint will convey some information about the system that other viewpoints omit. (You would use the same technique when describing any complicated construction such as a building, an aircraft, a novel or a painting).  Possible viewpoints might be:
  * the business model the software supports,
  * the user interface,
  * the dynamic behaviour of the system,
  * how data flows through the system,
  * what data types are implemented in the system,
  * what algorithms are implemented in the system,
  * the static architecture of the system, i.e. how the code is partitioned into modules, etc.

A common approach is to first define the user or business requirements, then describe the static architecture, identify modules and groups of closely connected modules, and then to apply other views to each of these groups. Fine details, specifically details of code, should be left out.

We strongly recommend that you make extensive use of diagrams, such as entity-relationship diagrams, UML diagrams, state charts, or other pictorial techniques.

As well as describing the system, it is important that you justify its design, for example, by discussing the implications of constraints on your solution and different design choices, and then giving reasons for making the choices you did. Typically these implications will relate to the aims of the project and to aspects of it discussed in the Background section.

The design of the system will almost certainly have evolved while you were developing it. Obviously you should describe its final state but often there are good reasons for describing intermediate states, too; for example, if you want to discuss the details of the design method used or to highlight learning that you later refer to in the Reflection section. If you do this, take special care to make sure the reader does not get confused between different stages of the design.

If you are not designing a system, but testing a hypothesis for a more scientifically oriented project, specification and design sections may not be required in quite the same form. The specification instead becomes a description of the problem and what is required of a solution. The design becomes a description of your approach to solving the problem and your suggested solution(s). For instance, if you are designing an algorithm to solve a particular problem you would have a problem statement section and then a section describing one or more suggested algorithms to solve the problem. Later in the Results and Evaluation section you then describe how to design experiments to test how well the algorithm(s) solve the problem and present your experimental results with an evaluation of your suggested solutions.

==== Implementation ====

Implementation is similar to the specification and design in that it describes the system, but it does so at a finer level of detail, down to the code level. This section is about the realisation of the concepts and ideas developed earlier. It can also describe any problems that may have arisen during implementation and how you dealt with them.

Do //not// attempt to describe all the code in the system, and do //not// include large pieces of code in this section. Complete source code should be provided separately. Instead, pick out and describe just the pieces of code which, for example:
  * are especially critical to the operation of the system;
  * you feel might be of particular interest to the reader for some reason;
  * illustrate a non-standard or innovative way of implementing an algorithm, data structure, etc.

You should also mention any unforeseen problems you encountered when implementing the system and how and to what extent you overcame them. Common problems are:
  * difficulties involving existing software, because of, e.g.,
    * its complexity,
    * lack of documentation;
  * lack of suitable supporting software;
  * complications with specific hardware or software platforms;
  * over-ambitious project aims.

A seemingly disproportionate amount of project time can be taken up in dealing with such problems. The Implementation section gives you the opportunity to show where that time has gone.

===== The "Results and Evaluation" =====

In this section you should describe to what extent you achieved your goals.

You should describe how you demonstrated that the system works as intended (or not, as the case may be). Include comprehensible summaries of the results of all critical tests that were carried out. You might not have had the time to carry out any full rigorous tests - you may not even got as far as producing a testable system. However, you should try to indicate how confident you are about whatever you have produced, and also suggest what tests would be required to gain further confidence.

This is also the place to describe the reasoning behind the tests to evaluate your results, what tests to execute, what the results show and why to execute these tests. It may also contain a discussion of how you are designing your experiments to verify the hypothesis of a more scientifically oriented project. E.g., describe how you compare the performance of your algorithm to other algorithms to indicate better performance and why this is a sound approach. Then summarise the results of the tests or experiments.
 
You must also critically evaluate your results in the light of these tests, describing its strengths and weaknesses. Ideas for improving it can be carried over into the Future Work section. Remember: no project is perfect, and even a project that has failed to deliver what was intended can achieve a good pass mark, if it is clear that you have learned from the mistakes and difficulties. 

This section also gives you an opportunity to present a critical appraisal of the project as a whole. This could include, for example, whether the methodology you have chosen and the programming language used were appropriate.

===== The "Conclusions and Future Work" =====

The Conclusions section should be a summary of the aims of project and a restatement of its main results, i.e. what has been learnt and what it has achieved. An effective set of conclusions should not introduce new material. Instead, it should briefly draw out, summarise, combine and reiterate the main points that have been made in the body of the project report and present opinions based on them.

It is quite likely that by the end of your project you will not have achieved all that you planned at the start; and in any case, your ideas will have grown during the course of the project beyond what you could hope to do within the available time. You can include discussion of future work in the conclusions or as a discussion at the end of the evaluation section. It is for expressing your unrealised ideas, focused in particular of what you suggest as next steps (possibly emerging out of your evaluation). It is a way of recording that 'I have thought about this', and it is also a way of stating what you would like to have done if only you had not run out of time (Remember to take into account Hofstadter’s Law: 'Everything takes longer than you think, even when you take into account Hofstadter's Law.'). Ideally it should provide a starting point for someone else to continue your work.

The Conclusions section marks the end of the project report proper. Be honest and objective in your conclusions.

===== The "Reflection" =====

We believe in the concept of "lifelong learning". One of the principles applied throughout the assessment during your studies is that of the value of reflection. We believe that it is important that we reflect upon our performance in order to identify "transferable learning", that can be carried over into future activities. Reflection should focus on what Argyris calls "double loop learning"; this is where we identify, not relatively "simple skills", such as the mastery of a new programming language, but the impact of what we have done on the assumptions, concepts and ideas we used to make decisions about our work. For example, a "reflective practitioner" would try to identify the characteristics of the problem that has been addressed, and consider whether assumptions or decisions about the relevant approach to solving that problem had been appropriate, in order to make a better decision in relation to problems that might be encountered in the future.
Site Tools

Page Tools
