Abstract:
Abstract gives a number of pointers to writing professional, structured technical reports. It is loosely aimed at engineers producing technical papers, reports, dissertations and theses. The ideas contained herein are necessarily subjective, but are based on writing and correcting reports over a period of about 16 years. Though writing style is inevitably individual, and refreshingly so, some basic principles are useful in guiding the prospective author in order to obtain a sound starting point and ease the daunting perspective of writing a lengthy document.
- 1. Document Structure
- 1.1 The contents list
- 1.2 Logical structure
- 1.3 Bite-sized chunks
- 1.4 Chapter order
- 1.5 Appendix material
- 1.6 Typical report sections
- 2. Writing Style
- 2.1 Who is the reporter?
- 2.2 Who is the reader?
- 2.3 Form
- 2.4 Justification and rationale
- 2.5 Observing the outside world
- 2.6 Writing conclusions
- 3. Multimedia and Visual Balance
- 4. Choosing a Word Processor
- 5. Quality Control
- 6. Conclusions
- Bibliography
1. Document Structure
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.
1.1 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 organization 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.
1.2 Logical structure
By logical structure is meant 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. Consider a good joke. It has the structure as shown in Fig.1:
In our case, the punch line is the set of conclusions. Everything should support the conclusions and naturally lead up to them. Remember this when constructing your contents list! A typical technical report has the following progression:
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.
1.3 Bite-sized chunks
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 prior establishment of the contents list also allows section numbers to be assigned to the different document sections, making cross-referencing relatively simple.
1.4 Chapter order
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 your 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.
1.6 Typical report sections
Depending on the nature of your 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 your work
Contents list
Which lists items from here on with appropriate page references, see Section 1.1
Abstract
Which summarizes 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
2. Writing Style
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.
2.1 Who is the reporter?
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.
2.2 Who is the reader?
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.
Failure to pitch the level correctly will also inevitably result in failure to communicate your ideas effectively, since the reader will either be swamped with complexity, or bored with blandness!
2.3 Form
This section deals with items related to general appearance and professionalism of the report.
2.3.1 Spelling
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 your 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 your mind (yet!). If the report language is not your first language, get a natural speaker to check your document.
2.3.2 Grammar
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 your sentences short and don't be afraid to ask somebody how to use punctuation correctly.
2.3.3 The capital dilemma
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 you wish to do this, or differentiate between different heading levels in a different way, make sure you are consistent in the way you do this.
2.4 Justification and rationale
Engineers and scientists are constant skeptics and need to be constantly re-assured that your work is pragmatic. For each idea presented, you should establish some rationale or motivation for its undertaking and any assumptions made must be justified. Similarly, critical assessment should be made of your 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 your report, it is also necessary to be aware (as fully as possible) of other work which has been carried out which relates to your 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 your 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 your own. Ensure you 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, you should provide enough information to allow the reader to access the source of your 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 your 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 your conclusions is then provided by the list.
3. Multimedia and Visual Balance
A technical report can contain information in a variety of forms. These include text, figures, tables and equations. The following subsections 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.
3.1 Figures
``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.
3.2 Tables
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.
3.3 Equations
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 you use is defined and beware of using the same mnemonic for two different variables!
3.4 Text
Text is the `filler' and provides the bridge between the equations, figures, tables and references. See Section 2 for more information on the form of the text.
4. Choosing a Word Processor
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.
4.1 Microsoft Word
This popular piece of bloatware (you can tell that this author is not a great fan!) from Bill Gates is by far the most popular worldwide. It sits happily in the Windows TM environment and provides inter-operability between other Windows-TM applications, giving you the opportunity to pull in graphs (e.g., from MATLABTM) or tables (e.g., from Excel) from other Windows TM applications. The main benefit is that Word is WYSIWYG i.e., your 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 (neither of which this author is very fond of) 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. This author's personal experiences with Word wouldn't be a major sell for Bill Gates!
4.2 Latex
La TeX [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 La TeX is considerably longer than for Word, explaining its relative lack of popularity. However, some context-sensitive editors are available for La TeX (such as WinEdt), which are a considerable help for people used to a Windows TM menu-based system. It is probably true to say that the La TeX 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). This document was produced in LaTeX.
|
5. Quality Control
Having completed the major chore of writing the document, you may consider that your work is complete. If there is a higher authority to whom the project/document is done under the guidance of, you may consider that it is their duty to do the quality control on it. Wrong! While your 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 your document lies with yourself. It is worth taking that extra small amount of time to ensure that your document is professional and is free from grammatical and spelling mistakes.
5.1 The schizophrenic author?
In proof-reading the document yourself, you 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 your ability to improve the document. Don't be tempted to gloss over sections or speed-read the text, happy in the knowledge that you know what's in there!
5.2 Some friendly help
If you are fortunate to have a colleague or friend from the target reader group who is willing to give you 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 you yourself are 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.
5.3 Your supervisor
Given that the document is a clear read (ensured by the two previous stages of quality control), your supervisor can provide some help regarding the technical accuracy of your 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 you want 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, you should get the best out of your document by ensuring that you observe the 3 stages of quality control. When you become well practiced at technical documents, just reviewing the document yourself (critically) may suffice.
6. Conclusions
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 you have a critical look at a similar type of document before you take your first steps. Is this report, in your 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, subsections and the use of tables, figure and references. It was written according to the methodology in Section 1, where each subsection has a core idea, making it very easy to write. No doubt, it has imperfections - here's your chance to improve on it! Aim to excel at your report writing. The professional nature of your reports will stand to you. 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.
