This shows you the differences between two versions of the page.
Next revision | Previous revision | ||
arranging_material_and_structuring_the_project_report [2011/11/11 14:49] – created scmfcl | arranging_material_and_structuring_the_project_report [2023/03/16 12:54] (current) – scmfcl | ||
---|---|---|---|
Line 1: | Line 1: | ||
====== Arranging Material and Structuring the Project Report ====== | ====== 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 " | ||
- | You should consider, at the beginning of your project, | + | All good project |
- | All good project | + | 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 |
- | Figure 3. shows an example of the layout we suggest for a project which implements a piece of software. You should vary the titles of the sections if these are inappropriate for your project – your supervisor is the best person to guide you on this. For the moment we will concentrate on the main body of the report and leave the supporting information until later. We recommend that you do the same when writing your report, though you should have a plan for your final report which will guide you on what material your should be retaining for eventual inclusion. | + | ===== The "Introduction" |
- | + | ||
- | Project reports describing projects whose aim has been to develop a particular software system tend to have a main body with a characteristic structure as illustrated above. For those which address a “softer” problem, these principles remain, though a more usual structure is shown in Figure 3. | + | |
- | + | ||
- | [[Figure 3.: Suggested report structure for a project which implements a piece of software.]] | + | |
- | [[Figure 3.: Suggested report structure for a project addressing a " | + | |
- | [[Figure 3.: Suggested report structure for comparing algorithms.]] | + | |
- | [[Figure 3.: Suggested report structure for the design and analysis of an algorithm.]] | + | |
- | + | ||
- | If the nature of the project is not to design and implement some software, but is more of an investigative or research nature, for example to compare two algorithms, a more suitable layout could be the one shown in Figure 3.3. Another project might involve the design and analysis of an algorithm. Here, there might be a lot of analysis of the problem and its solution and little to say on the systems aspect or user interaction, | + | |
- | + | ||
- | We look at each of the general sections of the report strucutre 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 at this stage to plan roughly how long each part should be, 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, | 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, | ||
- | * the aim(s) or goal(s) of the project; | + | * the aim(s) or goal(s) of the project, |
- | * the intended audience or “beneficiaries” of the work done; | + | * the intended audience or "beneficiaries" |
- | * the scope of the project; | + | * the scope of the project, |
- | * the approach used in carrying out the project; | + | * the approach used in carrying out the project, |
- | * assumptions on which the work is based; and | + | * assumptions on which the work is based and |
* a broad summary of important outcomes. | * a broad summary of important outcomes. | ||
- | ===== The “Background” ===== | + | ===== 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 | + | 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 wider context of the project, |
- | * the problem that has been identified; | + | * the problem that has been identified, |
- | * likely stakeholders within the problem area; | + | * likely stakeholders within the problem area, |
- | * any theory associated with the problem area; | + | * any theory associated with the problem area, |
- | * any constraints on the approach to be adopted; | + | * 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; | + | * 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; | + | * methods and tools that your solution may be based on or use to solve the problem, |
* and so on. | * 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, | + | 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, |
Relevant existing products, documents or artefacts that you should mention could be ones that, for example, | Relevant existing products, documents or artefacts that you should mention could be ones that, for example, | ||
- | * are similar to the one you are proposing; | + | * are similar to the one you are proposing, |
- | * support your project; | + | * support your project, |
- | * your project aims to extend or replace; | + | * your project aims to extend or replace, |
- | * demonstrate the “deficiencies” your project intends to address. | + | * demonstrate the "deficiencies" |
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, | 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, | ||
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 | 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 | ||
- | |||
< | < | ||
- | The Descartes language is like a restricted version of Pascal but with the following extra features: ... | + | The Descartes language is like a restricted version of Pascal but with |
+ | the following extra features: ... | ||
</ | </ | ||
Line 64: | Line 52: | ||
**Example 1:** | **Example 1:** | ||
- | |||
< | < | ||
Aim: | 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. | + | 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): | 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, | + | 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, | ||
+ | robust software package. | ||
</ | </ | ||
**Example 2:** | **Example 2:** | ||
- | |||
< | < | ||
Aim: | 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. | + | 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): | 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 | + | 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 | ||
+ | terms of the organisation's survivability, | ||
+ | strategy, and develop and assess an alternative set of activities to | ||
+ | achieve the stated vision. | ||
</ | </ | ||
- | ===== The “Specification | + | ===== The "Specification, Design |
- | The purpose | + | This is one suggestion for the description |
+ | |||
+ | ==== Specification and Design | ||
+ | |||
+ | The purpose of specification and design | ||
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). | 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). | ||
- | * the business model the software supports; | + | * the business model the software supports, |
- | * the user interface; | + | * the user interface, |
- | * the dynamic behaviour of the system; | + | * the dynamic behaviour of the system, |
- | * how data flows through the system; | + | * how data flows through the system, |
- | * what data types are implemented in the system; | + | * what data types are implemented in the system, |
- | * what algorithms 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. | * 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, | A common approach is to first define the user or business requirements, | ||
- | We strongly recommend that you make extensive use of diagrams, such as entity-relationship diagrams, UML diagrams, state charts, or other pictorial techniques | + | 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. | 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. | ||
Line 104: | Line 109: | ||
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. | 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 (see [[Figure 3.]] and [[Figure 3]].). 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. | + | 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. |
- | ===== The “Implementation” ===== | + | ==== Implementation ==== |
- | The Implementation | + | Implementation is similar to the specification |
- | 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 | + | 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; | * are especially critical to the operation of the system; | ||
* you feel might be of particular interest to the reader for some reason; | * 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... | + | * 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: | 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: | ||
Line 120: | Line 125: | ||
* lack of documentation; | * lack of documentation; | ||
* lack of suitable supporting software; | * lack of suitable supporting software; | ||
+ | * complications with specific hardware or software platforms; | ||
* over-ambitious project aims. | * 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. | 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” ===== | + | ===== The "Results and Evaluation" |
In this section you should describe to what extent you achieved your goals. | 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. | + | 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. | 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. | ||
Line 136: | Line 142: | ||
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. | 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 “Future Work” ===== | + | ===== The " |
- | It is quite likely that by the end of your project | + | 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 |
- | ===== The “Conclusions” ===== | + | It is quite likely that by the end of your project |
- | + | ||
- | 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 | + | |
The Conclusions section marks the end of the project report proper. Be honest and objective in your conclusions. | The Conclusions section marks the end of the project report proper. Be honest and objective in your conclusions. | ||
- | ===== The “Reflection” ===== | + | ===== 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”, | + | |
- | + | ||
- | ===== The “References” ===== | + | |
- | + | ||
- | In [[???]] we said that you should relate your work to that of other people. Other work explicitly cited should be listed in the Reference section and referred to in the text using some kind of key. It is important that you give proper credit to all work that is not strictly your own, and that you do not violate copyright restrictions. | + | |
- | + | ||
- | It may be desirable to provide a Bibliography section separately from the reference section. In general, references are those documents/ | + | |
- | + | ||
- | References should be listed in alphabetical order of author’s surname(s), and should give sufficient and accurate publication details. For example, | + | |
- | < | + | |
- | Chikofsky, EJ, Cross, JH. 1990. Reverse Engineering and Design Recovery: A Taxonomy. IEEE Software, 7(1): | + | |
- | + | ||
- | Date, CJ. 2000. An Introduction to Database Systems, 7th Edition. Addison-Wesley. | + | |
- | </ | + | |
- | are acceptable references. | + | |
- | + | ||
- | There are various conventions for quoting | + | |
- | < | + | |
- | For more information see [Chikofsky et al, 1990]. A more detailed description is given by Date [2000]. | + | |
- | </ | + | |
- | + | ||
- | There are several other variations. For example, some authors prefer to use only the first three or four letters of the name, e.g. [Chi1990] or just to number the references sequentially, | + | |
- | + | ||
- | Whatever convention you choose, be consistent. | + | |
- | + | ||
- | Information Services provide a number of leaflets which describe in detail accepted ways of presenting references. For example, guidance on the Harvard Style of citing and referencing may be viewed at | + | |
- | http:// | + | |
- | + | ||
- | Whatever style of referencing you adopt, it is critical that you are assiduous in acknowledging the sources you have used; failure to do so may lead to suspicions of unfair practice and an investigation into whether or not your work reflects the standards expected of academic research. Guidance on plagiarism and how to avoid it is available at | + | |
- | http:// | + | |
- | + | ||
- | Note that it is seldom sufficient to simply “cut and paste” material from other sources. When you take material from someone else’s work, you are doing so because it helps support your argument, or justify decisions you are making. It is therefore essential to make it clear why you have included material from other sources; in other words, you need to critically assess the work of others, whether it is supporting your position or not: | + | |
- | * If the material you are citing from another source supports your position, you must explain why it should be trusted. For example, material from a published journal will, normally, have been peer-reviewed and can therefore be considered to have some validity, according to subject matter experts. Much of what is published on the Internet cannot be regarded in the same way, however. | + | |
- | * You will often find that there are conflicting views in the published material; in such cases you must explain which view you favour and why, before relying on the material to support your position. | + | |
- | * If other writers have taken a different position to the one you support, you must explain why the reader should accept your ideas rather than those proposed elsewhere. | + | |
- | In summary, you need to ensure | + | We believe in the concept of " |