Report Writing
Report Writing is a very important writing for students especially those who are pursuing their first degree.
One major difficulty with a large document is the rather onerous task of addressing a full pad of blank paper. Additionally, the task of achieving good structure from the start is compounded by the myriad of thoughts which one juggles, in an attempt to sort out the logical progression of the document. Failure in this endeavour will surely result in structural changes at a later stage, which are the most costly of revisions. The key to achieving both good structure (from the start) and decomposing the initially large problem into bite-sized chunks lies in the contents list.
For most people, the contents list is a summary of the chapter and section headings, together with a page index, and is normally written when the document is already complete. However, the contents list is the one place in the document where overall structure can be examined, so why not get the structure right at the start? Early organisation of the contents list is certainly not a trivial problem and may take up to a few days to draft. The level of detail should go down to (probably) sub-subsections, where the final level contains one key idea and takes up, at most, two to three paragraphs of text. It may even be useful to title each paragraph, though this may not appear in the final contents list as a formal heading.
Again, it is important to stress that laying out the contents list is not easy. However, some hard work at this stage will save a lot of grief later on and is pro-active in ensuring good structure. A badly structured document inherits its own inertia and will be very difficult (and laborious) to correct at a later stage.
Logical structure means the natural unfolding of a story as the reader progresses through the document. This is achieved by going from the general to the specific, with the background material preceding the technical expose, which should lead logically to the conclusions.
In this case, the punch line is the set of conclusions. Everything should support the conclusions and naturally lead up to them. Remember this when constructing the contents list!
If some of the detail is standard, but possibly difficult to obtain, it can be included as an appendix. More information on appendices is given in Section 1.5.
From the hierarchical structure in the contents list, it should now be possible to write each of the sub-subsections (or paragraphs) as a more-or-less independent entity, observing however, the relationship between different sections. The a priori establishment of the contents list also allows section numbers to be assigned to the different document sections, making cross-referencing relatively simple.
With a technical document, it is often beneficial to write the technical chapters first i.e., the core material, leaving the introduction, discussion and conclusions until the end. This is especially important when some results are still not available and the time has come to begin writing the document. Even in cases where all results are available, leaving the introduction until the end allows a better perspective to be had on the document as a whole.
1.5 Appendix material
Many authors are uncertain as to what to include in the appendix section. Generally, appendices should contain relatively standard derivations and perhaps lists of parameter values, which would interfere with the continuity of the main body of the document. In particular, the appendix section should not contain:
· All the figures corresponding to the document. Ideally these should appear alongside the appropriate text, or else after the references in a separate section.
· Photocopies of data sheets, or other easily-accessible material.
· Any material which is crucial to the continuity or flow of the `story' in the main technical sections.
As with the main document sections, the appendices should reference all material which is not the authors original work (see Section 2.5). All appendices should be numbered consecutively, for example Appendix A1, Appendix A2, etc., in order to allow cross-referencing from the text.
Depending on the nature of the document, it may (optionally) have the following sections:
Title page
with name, affiliation, date, etc.
Dedication
to a friend, family member, or loved one
Declaration
that the material in the report is the author's own work
Acknowledgement
to those who have helped or influenced the work
Contents list
which lists items from here on with appropriate page references, see Section 1.1
Abstract
which summarises the report contents
Introduction
which introduces the work, provides the motivation and context and outlines other related work
Main technical chapters
which document the core technical work
Conclusions
which may also identify appropriate future work, see Section 2.6
References
see Section 2.5
Appendices
see Section 1.5
Writing style is probably the most individual aspect of a report, but again there are useful guidelines which aid the readability, professionalism, objectiveness and impact of a report.
All reports should be written in the third person i.e., as an objective observer! Avoid using terms such as ``I did this experiment and ..". Instead substitute terms, such as ``The experiment was performed ...''. Note that the best written description is not necessarily the same as the best verbal description.
Decide, in advance of writing, who the likely reader of the document is. The document must be pitched at an appropriate level with sufficient background to allow understanding by the target audience. Examples of target audiences are shown in Table 1.
|
Table 1: Example target audiences |
||||||||
|
Failure to pitch the level correctly will also inevitably result in failure to communicate the ideas effectively, since the reader will either be swamped with complexity, or bored with blandness!
This section deals with items related to general appearance and professionalism of the report.
This may seem a small an unimportant point for an engineering text, but poor spelling makes a document seem sloppy and may convey an impression that the engineering content is as loose as the general appearance! There are spelling checkers in virtually every word processor now , so use them! However, don't assume that a spelling checker will get all typos, so long as the word is in its dictionary, it won't flag an error. These checkers are good, but they can't read the mind (yet!). If the report language is not one's first language, get a natural speaker to check the document (see Section 5.2).
Same here as for spelling. Many word processors now have grammar checkers as well as spell checkers, but the usefulness of these is debatable, so don't rely on them. If in doubt, keep the sentences short and don't be afraid to ask somebody how to use punctuation correctly.
Avoid excessive use of capital letters. One recommendation is to only use capitals for proper nouns (such as place names, company names, etc) and in places where acronyms are being defined, e.g., Asynchronous Transfer Mode (ATM). Acronyms should be defined at the first point of usage and the acronym can then be used freely. Try to avoid the use of capitals for emphasis, use boldfacing or italics instead. Capitals can be used effectively to differentiate between different section heading levels, such as in this document i.e., the next level up uses capitals to start each word in the subsection title. However, if one wishes to do this, or differentiate between different heading levels in a different way, make sure consistency is observed.
Engineers and scientists are constant skeptics and need to be constantly re-assured that their work is pragmatic. For each idea presented, one should establish some rationale or motivation for its undertaking and any assumptions made must be justified. Similarly, critical assessment should be made of the results.
2.5 Observing the outside world
Plagiarism is an unacceptable breach of copyright, where an author presents methods, text or results as his/her own, without reference to the original source. Ignorance of the original source or a forgetful omission is no excuse and the consequences for plagiarism are serious where it appears in examinable documents. However, in addition to referencing work which is included in the report, it is also necessary to be aware (as fully as possible) of other work which has been carried out which relates to the research. This becomes very important in MEng/PhD theses and research papers, which sit on the world stage and require that the author be aware of all related works. Searching for related literature can be performed by computerised searches through databases, such as INSPEC and Compendex, or by directly searching through journals. The Internet can also sometimes be a useful source of information.
Make sure that the referencing method is one of the popular ones (such as the Harvard or MLA styles [1]). There's absolutely no point in inventing another system of one's own. One must know how to correctly reference:
· A journal paper [2]
· A conference paper [3]
· A PhD/MEng thesis, final-year project or research report [4,5]
· A book [6]
· An Internet source (via the URL) [7].
As a basic requirement, one should provide enough information to allow the reader to access the source of the material. The examples shown follow the general form used by the IEEE: numerical order, in order of appearance. This form is frequently used in other engineering journals and books, though the Harvard style [1] is also popular.
2.6 Writing conclusions
Conclusions must conclude! They must give some overall insight into the value of the work in general and inform the reader of what the major impact is, together with any caveats which the reader should be aware of. A popular `cop-out' is to fill the conclusions section with a summary of what's in the technical chapters. This concludes nothing! The summary (if present) should be at the start of the document as an abstract. It may be helpful to flag items on a list, which are appropriate for the conclusions section, while writing the technical chapters. The key to the conclusions is then provided by the list.
A technical report can contain information in a variety of forms. These include text, figures, tables and equations. The following sub-sections contain some information regarding the appropriate use of each. However, choosing different means of representation can also be used to give visual balance to the document, for example by breaking up long sections of text with equations, tables or figures. In cases where several options are available for representing a particular piece of information, the author can choose appropriately to make the document a less daunting prospect to the reader through visual balance. In most cases, however, the appropriate choice of medium is dictated by the type of information to be communicated.
``A picture tells a thousand words''? There is great substance in this statement, and nowhere more obvious than in technical reports. Use figures liberally to communicate specific results (graphs) and show an overview of the system being described through block diagrams, etc. Where possible, put multiple plots on the same axes, so that comparative conclusions can be drawn. Ensure that each figure has a number and a title, so that it can be referenced from the text.
Tables are an excellent means of giving an overview of numerical results or providing information in a form which lends itself to comparison. Again, ensure that each table has a number and a title, so that it can be referenced from the text.
Some authors shun the formality of equations, preferring to describe the required relationships in textual form. However, it is generally possible to encapsulate a whole paragraph of such text in a single equations. Use equations in a technical report where possible! Number all equations consecutively to allow reference from the text. Be careful that all the notation used is defined and beware of using the same mnemonic for two different variables!
Text is the `filler' and provides the bridge between the equations, figures, tables and references.
There is currently a great variety of word processor software available. Two of the popular packages for producing technical documents are briefly reviewed here, along with comparative advantages and disadvantages. See Table 2 for some itemised comparisons.
This popular piece of bloatware from Bill Gates is by far the most popular worldwide. It sits happily in the WindowsTM environment and provides inter-operability between other WindowsTM applications, giving one the opportunity to pull in graphs (e.g., from MATLABTM) or tables (e.g., from Excel) from other WindowsTM applications. The main benefit is that Word is WYSIWYG i.e., the document appears on the screen as it will be (barring a few Microsoft funnies) in printed form. Word also has an equation editor and an in-built drawing package and a table `wizard', for easy generation of tables. Overall, easy to use and quick to learn, but the `intelligent' automatic corrections it does are particularly infuriating with a technical document, which may have a lot of non-standard text. The major drawbacks are the relatively large file sizes, which can lead to other problems, such as unexpected software crashes, with possible loss of input.
LaTeX [8] is a suite of (largely shareware) typesetting software, which gives excellent output. The main drawback is that it isn't WYSIWYG, a mark-up language (similar to HTML) being used to specify formatting commands, math symbols, etc. As a result, the learning curve for LaTeX is considerably longer than for Word, explaining its relative lack of popularity. However, some context-sensitive editors are available for LaTeX (such as WinEdt), which are a considerable help for people used to a WindowsTM menu-based system. It is probably true to say that the LaTeX system has been adopted by the majority of researchers in the area of mathematical sciences for the preparation of technical documents. The main advantages are that file sizes are small and it has excellent (and easy-to-use) cross referencing systems for:
· References
· Equations
· Tables, and
· Figures
as well as good facilities for producing mathematical mark-up (symbols, equations, etc).
|
Table 2: Comparison of word processing software |
||||||||||||||||||||||||
|
Having completed the major chore of writing the document, one may consider that the work is complete. If there is a higher authority to whom the project/document is done under the guidance of, one may consider that it is their duty to do the quality control on it. Wrong! While the supervisor may suggest modifications to structure or provide suggestions on some technical points, it is not their job to correct spelling, grammar, etc. The primary responsibility for the quality of the document lies with oneself. It is worth taking that extra small amount of time to ensure that the document is professional and is free from grammatical and spelling mistakes.
In proof-reading the document oneself, one should attempt to look at the document in a fresh light as a reader completely new to the material. The capacity to adopt this `schizophrenic' stance will greatly aid one's ability to improve the document. Don't be tempted to gloss over sections or speed-read the text, happy in the knowledge that one knows what's in there!
If one is fortunate to have a colleague or friend from the target reader group who is willing to give a little time, the view of an objective and completely fresh reader can be of great benefit. This person may also be able to pick up spelling or grammatical errors which one is unaware of. The use of a friend or colleague at this stage is vital in cases where the document is not written in the author's first language.
Given that the document is a clear read (ensured by the two previous stages of quality control), the supervisor can provide some help regarding the technical accuracy of the report. The converse is also true, in that the lack of clarity in the first place will inhibit the refinement of the technical content! If one wants to get the best, in terms of advice on possible technical improvement, the document must be relatively error free. If a supervisor is prepared to correct typos, grammar, etc., it is unlikely that he/she is going to have time to focus on the more important technical points. In short, one should get the best out of the document by ensuring that one observes the 3 stages of quality control. When one becomes well practiced at technical documents, just reviewing the document oneself (critically) may suffice.
This note has attempted to highlight the salient features of technical report writing. It is not a comprehensive guide. It is motivated by a large number of reports which this author has seen which have not nearly done justice to the work which they were intended to report on. It is as important to report well on the work as to perform good technical work. Consider the case of a BEng project report in the School of Electronic Engineering at DCU, as an example, where 60% of the marks are allocated on the basis of the report alone. This mark is indicative of the relative importance attached to reporting in the wider industrial community. For further reading see, for example, the volume by Beer [10].
Learn by example! Make sure one has a critical look at a similar type of document before one takes his/her first steps. Is this report, in one's opinion, clear and well written? Try not to make the same mistakes as that author made!
Finally, this report was specifically structured to demonstrate sections, sub-sections and the use of tables, figure and references. It was written according to the methodology in Section 1, where each sub-section has a core idea, making it very easy to write. No doubt, it has imperfections - here's the chance to improve on it! Aim to excel at the report writing. The professional nature of the reports will stand. Remember that ideas committed to print will potentially be perused by a considerable number of people (including potential employers!) over a considerable period into the future.
1 Byrne, N. Citing and Referencing - A Guide for Students, Dublin City University Library, 1998.
2 Hirschorn, R.M. and Miller, G. Control of nonlinear systems with friction, IEEE Trans. on Control System Technology, Vol.7, No.5, Sept. 1999.
3 Whitfield, A. and Wallace, F.J. Study of incidence loss models in radial and mixed-flow turbomachinery, Proc. Cong. Heat Fluid Flow in Steam and Gas Turbine Plant, Univ. Warwick, Coventry, UK, April 1973, pp 122-32.
4 Murray, F. Time Series Forecasting Methodologies for Electricity Supply Systems, PhD Thesis, Dublin City University, 1997.
5 O'Connor, M. Computer-Based Control of Time Delay Systems Using a Smith Predictor, BEng Project Report, School of Electronic Engineering, Dublin City University, 1989.
6 Kreyszig, E. Advanced Engineering Mathematics (7th Ed.),, Wiley, 1993.
7 Ringwood, J. and Galvin, G. Artificial Neural Networks - An Introduction, Available from: eeng.dcu.ie/~annet/ [Accessed 15th Nov. 1999].
8 Lamport, L. LaTeX : A Document Preparation System : User's Guide and Reference Manual (2nd Ed.), Addison-Wesley, 1994.
9 Gratzer, G. Math into TeX : : A Simple Introduction to AMS-LaTeX, Birkhauser, 1993.
10 Beer, D.F. (Ed.) Writing and Speaking in the Technology Professions - A Practical Guide, IEEE Press, 1992.
Adapted from various sources - individuals & the Internet