ITEE Home » » Datasheets » Guidelines for Technical Writing

Print version

Paul Murtagh and Kurt Sterzl
Department of Electrical and Computer Engineering
The University of Queensland
13th October 1995

---

Contents

• Preface
  
  
• I Writing Techniques
  
• Introduction
• Steps for Writing
• Improving Your Writing
  • How to Write Better Paragraphs
  • How to Write Better Sentences
  • How to Choose the Right Word
• Creating and Integrating Graphics
• Improving Page Design
  
  
• II Writing Experimental Reports
  
• Introduction
• Overview of the Sections
  • The Title Page
  • The Abstract
  • The Table of Contents
  • The Introduction Section
  • The Theory Section
  • The Design Section
  • The Implementation Section
  • The Procedure and Apparatus Section
  • The Results Section
  • The Discussion Section
  • The Conclusion Section
  • The References Section
  • The Appendices
• References

---

Preface

As an engineer, you will be required to document the work you perform in a laboratory or out in the field. When performing research or examining alternative approaches to solve a certain problem, you may need to devise experiments to test your ideas. After the experiments have been finished, it is then necessary to formally document your idea either for company reports or for publication.

As a student, you are given experiments to perform (i.e. you do not need to devise your own experiments). However, as you move from second year to third year and finally to fourth year, you will need to provide more input as to how the experiment is to be carried out. Eventually, the experience you have obtained in carrying out experimental procedures and documenting your idea, will be required for your undergraduate final year thesis project. Hence, the purpose of these experiments are two-fold:

1. they give you a practical understanding of laboratory procedures, and
2. they give you the opportunity to develop your skills in technical writing by having to document the experiments as if you, the student, have actually devised the experiment to examine a certain idea or method.

The report should be written in such a way that it demonstrates your knowledge of that particular field and the interpretation of the results obtained from the experiment. The aim of these guidelines are to help you understand how the information obtained, from idea to experiment, is organised and presented on paper.

This document provides an overview of how to write better technical documents. The document is split into two parts. The first part describes how to write effective reports covering the following areas:

• Steps commonly used for writing effective documents.
• Steps for improving your writing.
• Incorporating tables and figures into documents.
• Improving the presentation of the document.

The majority of this section was summarised from Markel [1]. Other books on technical writing of interest are [2-6].

The second part provides an outline for typical experimental reports. Each section of the report is covered in detail hopefully to clear up any misunderstanding about what to include in an experimental report. A number of common errors are provided in Jordan [6] for each section in an experimental report.

---

Part I

Writing Techniques

Introduction

There are a number of characteristics of an effective document. These characteristics can be summarised as follows:

• The document should include all the information the readers need. This means including important information {\bf relevant} to the document as an appendix and cross reference or cite documents that contain less important information.

  An effective document should also provide a background section (eg. background theory) if the audience includes readers unfamiliar with the topic. This document should also include a clear description of the writer's methods, as well as a complete statement of the principle findings. These findings include the results, observations (discussion), and any conclusions.
  
  

• The document should be structured so that readers can easily locate the information they seek. Some readers are interested in only one or several sections of a document. Other readers might read most of them. But relatively few people will read the whole document from start to finish, like a novel.

  To achieve this, discussions should be self-contained, and headings and lists easy to identify. Also for reports, a detailed table of contents should be given.
  
  

• Your writing should be as concise as you can make it without sacrificing content. One way to shorten a document is to replace long words and phrases with short ones. Short documents are better than long documents.
  
  
• Workplace writing is meant to get a job done, not to show off your personal style. The reader should be thinking about the subject you are writing about and not about you.
  
  
• Always acknowledge your use of other people's ideas or words by citing them. This involves referring to information that you may have read by citing the document from which it came (and possibly the section in the document if it is a book).

Steps for Writing

This section discusses the steps commonly used to write effective documents. This involves gathering your ideas, organising them, drafting the document, and finally revising the document.

• Generate ideas to include in the document.
  Before you start writing, you must decide what information the document will contain. One particular method for generating ideas is {\em brainstorming}. Brainstorming involves quickly listing all the ideas that might be appropriate for the document. Write ideas quickly without trying to organise them; this organisation will be done next.
  
  
• Organise your ideas using some kind of outline.
  This involves ordering your ideas into some structured pattern. Examples of patterns are:
  
  
  1. Chronological
     This pattern is useful if the reader needs to follow your discussion in order to perform a task.
     
     
  2. Classification
     This involves placing items into logical categories.
     
     
  3. Partitioning
     This involves breaking a single entity into its logical components.
  
  
• Write the draft quickly.
  This involves quickly turning your outline into sentences and paragraphs. Don't worry about individual words and sentences; leave this until the revising stage.
  
  
• Spend your time revising the draft.
  After writing the draft, leave the document for as long as possible. When revising the draft, the following areas should be looked at:
  
  
  1. Comprehensiveness
     Have you covered everything in your outline, and have you gone into sufficient detail to make the message clear?
     
     
  2. Accuracy
     Make sure all your data and statements are accurate.
     
     
  3. Organisation
     Does the information follow a clear and logical order?
     
     
  4. Emphasis
     Provide the same level of information on each subpoint? If a certain point needs more clarification than another, then structure the discussion accordingly.
     
     
  5. Paragraphing
     Does each paragraph have a clear topic sentence that summarises the information that follows? Is the paragraph logically organised and developed?
     
     
  6. Style
     Check for sentence variety (don't keep using the same phrase over and over), grammar and punctuation mistakes, and awkward sentence constructions.
     
     
  7. Spelling
     Always check for spelling mistakes by using either a spell checker or having someone else read the document. Spelling errors are almost always visible when someone else reads the document.

Improving Your Writing

This section discusses ways to improve the coherence of your writing. This means that the document should follow from one idea to the next smoothly without having to re-read the sentence or paragraph to grasp its meaning. The reader should be able to read the document once without getting lost by what you are saying.

• Use informative titles and headings.
  Titles and headings should be sufficiently precise and easy to read and understand.
  
  
• Use lists to communicate parallel information.
  Many sentences become quite long and complicated. Information that is parallel should be presented as a list, either vertically or horizontally. These lists can either be numbered or listed using bullets.
  
  
• Use introductions to forecast discussions.
  Because you know the subject better than the reader, you must adequately explain what information you are going to present, how you're going to present it, and why you're presenting it that way. The questions you need to ask yourself are:
  
  
  1. What is the subject?
  2. What is the purpose of the discussion?
  3. What is the background of the subject?
  4. What is the scope of the discussion?
  5. What is the organisation of the discussion?
  6. What are the key terms that will be used in that discussion?
  
  
• Use conclusions to complete discussions.
  This is done by answering the following questions:
  
  
  1. What are the main points established in the document?
  2. What should be done next?
  
  The second question would only need addressing if there is any future work involved.

How to Write Better Paragraphs

This subsection discusses the structure of effective paragraphs. Effective paragraphs simply state the idea and then explain or defend it. Hence, paragraphs begin with a clear topic sentence, and then support this idea logically. The paragraph should contain certain words and phrases to help the reader make the transition from one sentence to the next. There are four steps in writing an effective paragraph:

1. Begin with a clear topic sentence.
2. Support the topic sentence logically.
3. Emphasise the coherence of the paragraph.
4. Keep paragraphs to a manageable length.

How to Write Better Sentences

This subsection describes how to improve the style of your sentences. Style is how you sound when someone reads what you have written. You need to be straightforward, clear, concise, unpretentious, authoritative, and easy to understand. You do not want to be pompous, unclear, and verbose.

• Use the active and passive voices appropriately.
  The active voice focuses on the performer of the action, whereas the passive voice focuses on the recipient of the action. The active voice is usually more precise and less wordy than the passive voice. In general, the active voice is preferable.
  
  
• Use appropriate tense.
  Whenever you quote or discuss previously published work (possibly your own), you should use the present tense. Whenever you present your own work (i.e. the work you did in an experiment), you must use the past tense.
  
  
• Choose appropriate sentence patterns.
  There are four types of sentences:
  
  
  1. Simple
     The simple sentence has only one independent clause.
     
     
  2. Compound
     The compound sentence has two independent clauses, linked by a semicolon or by a comma and one of the seven coordinating conjunctions: and, or, for, nor, so, but, and yet.
     
     
  3. Complex
     The complex sentence has one independent clause and at least one dependent clause.
     
     
  4. Compound-complex
     The compound-complex sentence has at least two independent clauses and at least one dependent clause.
  
  

  The most useful types of sentences for technical writing are the simple and complex. Further details of these sentence types can be found in Markel [1].
  
  

• Use modifying elements effectively.
  There are two types of modifiers:
  
  
  1. Restrictive Modifiers
  2. Non-restrictive Modifiers
  
  

  Restrictive modifiers restrict the meaning of the word (i.e. they make the word more specific). Non-restrictive modifiers simply provide extra information about the word.
  
  

• Keep parallel items parallel.
  Do not turn parallel information into sentences. Either use a list, or number each item in the sentence.

How to Choose the Right Word

• Choose simple, clear words and phrases.
  Picture yourself speaking on the phone to a good friend. If you would be embarrassed to have the person hear what you have written, change it.
  
  
• Replace fancy words and phrases with plain words and phrases.

Creating and Integrating Graphics

• Determine whether you need graphics.
  Do not construct tables unless repetitive data must be presented. Do not simply present reams of data because you have them in your workbook; only present the important information.
  
  
• Determine what kind of graphic to use.
  If a graph presents that data better than a table (i.e. it shows the significance between certain values better), then use a graph.
  
  
• Make the graphic self-sufficient.
  Support the figure or table with text to allow the reader to examine the figure without having to read the supporting text to understand its significance. Always label axes on graphs (also giving units). Do not simply reproduce a CRO screen; graph the data you obtained from the CRO.
  
  
• Determine where to put the graphic.
  Place the graphic as close to the reference in the text as possible. Normally, it is placed on the same page or the page following.
  
  
• Tie the graphic to the text.
  This involves introducing the graphic and explaining its significance, cross-referencing appropriately (eg. Figure 1: Title of figure) and referring to the label Figure 1, or Fig. 1, in the text. Tables and figures should use separate numbering sequences.

Improving Page Design

This section lists a number of areas for improving the clarity of the information contained on the page.

• Leave adequate margins.
• Use appropriate line spacing.
• Use appropriate justification.
• Use easy-to-read fonts.
• Use different members of a single type family.
• Use type sizes appropriately.
• Use uppercase and lowercase.
• Design titles and headings for emphasis and clarity.
• Design lists for clarity.
• Include page numbers on all pages.

---

Part II

Writing Experimental Reports

Introduction

What follows is a concise summary of guidelines for report writing for Electrical and Engineering Students. This guide should be used in conjunction with the Written Laboratory Report Mark Sheet. A more detailed explanation of experimental report writing is described by Jordan and Andrews [6].

Reports have evolved as a distinctive form of literature for the rapid communication of information on specific topics. To fulfil this role effectively, it is essential for the report to present the information in the best possible manner to the potential reader.

An engineering report is a document which formally states the results of, or progress made with, a research and/or development investigation, which, where appropriate, draws conclusions and makes recommendations, and which is initially submitted to the person or body for whom the work was done.

Overview of Sections

The following outline, preferably in the order in which they are listed, should be used:

• The title page.
• The abstract.
• The table of contents.
• The introduction section.
• The theory section.
• The design section.
• The implementation section.
• The procedure and apparatus section.
• The results section.
• The discussion section.
• The conclusion section.
• The reference section.
• The appendices.

Some sections may be inappropriate in some reports and occasionally you may need to invent a new sectional heading or use a different name. Although it is uncommon in practice to use some of these headings (eg. Theory, Procedure, Results, and Discussion) since they are too vague, it is advised that the student follows these headings as closely as possible for marking purposes.

The Title Page

The title page should be concise and should indicate the subject of the report clearly and succinctly. It should include the organisations' name (in this case ``Department of Electrical and Computer Engineering, The University of Queensland''), the title of the report, and the authors name and date.

The Abstract

The abstract should be an informative summary of the entire report. A concise description of the methods, results and significance of the report should be included, but the mere expansion of the title should be avoided. The emphasis to be placed on various aspects will depend on the nature of the individual work being reported. As the writing of the abstract is one of the most important tasks particular attention should be paid to it. The abstract should: (1) state the principle objectives and scope of the investigation, (2) describe the methods employed, (3) summarise the results, and (4) state the principle conclusions.

The Table of Contents

A table of contents is required for all but the very shortest of reports (no more than a few pages). The principal headings should be listed verbatim and in the order in which they appear in the report, together with the page number on which each of them begins.

The table of contents should follow the abstract and shall begin on a separate page. The table of contents does not include itself.

The Introduction Section

Every report should have an introduction section which includes in the first paragraph a succinct statement of the objective of the work reported. The introduction should bring out the salient features of the work in a concise manner. It should not anticipate what is to be said in later sections of the report except in the broadest outline and, in particular, it should not include:

• A detailed experimental procedure and/or theoretical reasoning.
• A detailed discussion of the results as a repetition of the discussion section.
• A simple repetition of the contents of the abstract (summary).

The Theory Section

In certain cases, the report may be primarily of a theoretical rather than an experimental nature. In such cases theory should be substituted for experimental procedure and results. Where results embrace a detailed theoretical treatise in addition to the experimental work, theory shall precede experimental procedure and results.

The Design Section

For experiments that require substantial design (eg. computer engineering practicals), a separate Design section should be included, preferably after any relevant theory. The design section should be split into three subsections as appropriate:

1. Design Specifications
   This subsection provides a detailed description of the design specifications including figures as appropriate.
   
   
2. Hardware Design
   This subsection should describe the design of any relevant hardware showing block diagrams and logic diagrams as necessary. This does not include the selection of any components at this stage; this is done in the next section. Simply state what type of component may be necessary (eg. parallel loading shift register).
   
   
3. Software Design
   The subsection describes the algorithm using a high level description such as a flow-chart or pseudo-code.

The Implementation Section

The implementation section should be split into three subsections as appropriate:

1. Component Selection
   This subsection discusses the selection of various components where alternatives exist and giving reasons for these selections (eg. chip count, functionality, power consumption, speed, etc.).
   
   
2. Hardware Implementation
   This subsection describes the actual implementation of the hardware using the components selected, and any modifications necessary because of certain restrictions on these components. Full schematics need to be given showing all pin numbers and device types. Schematics that occupy a number of pages should be placed in an appendix. When describing a certain section of the hardware in the text, this section of hardware should be placed as a figure in the main text at the relevant location.
   
   
3. Software Implementation
   This subsection describes the actual implementation of the software using a particular language (eg. the C language). Descriptions should be given for any unusual data structures, methods, etc. that are not apparently clear. All code should be given, preferably as a figure, in the main text. Code that occupies a number of pages should be placed in an appendix. When describing a certain section of the code in the text, this section of code should be placed as a figure in the main text at the relevant location.

The Procedure and Apparatus Section

This section concerns the manner in which the work was carried out. Emphasis should be given to anything new; only very brief details of standard apparatus and techniques should be presented. If it is desired to bring out experimental aspects in greater detail, these should be presented as an appendix.

As a general guide, details should be just sufficient to enable an adequately skilled worker in the field to retrace the steps of the investigation without undue difficulty. Steps that are not outlined in the Procedure section of the experimental sheets should be included here to clarify ambiguities.

The Results Section

This section concerns the results that were obtained. All graphs should be included in this section. Tables that are the basis of these graphs can be included as an appendix. In experiments that involve design (eg. computer engineering experiments) rather than observation/measurement the Results section could be excluded.

The Discussion Section

The discussion is the interpretation of and/or commentary on the results and the reasoning on which the conclusions are founded. It may also attempt to shed light on the work in terms of new or extended principles or theories in the field covered. Even though it may be difficult to separate the discussion from the preceding procedure and results sections, wherever it is practicable a separate section should be formed.

The Conclusion Section

Conclusions should be clearly presented in a precise manner; unnecessary matter should not be allowed to detract from clarity.

The conclusions represent a clear and orderly, sometimes numbered, presentation of the deductions made after full consideration of the results of the work. Quantitative data are not inappropriate but the details of an involved argument of result should not be included.

The Reference Section

Bibliographical references shall be provided for works mentioned in the text and shall be listed and numbered in the order in which they first appear in the text. To avoid ambiguity it is recommended that titles of periodicals should not be abbreviated. Refer to various text books and journals that appear in the library for examples of referencing.

References to books should contain (in this order), the author's name/s, the title of the book, the publisher, and the date of publication. References to journal papers should contain, the author's name/s, the title of the paper, the title of the journal, the volume number, the issue number, the page numbers where the paper appears, and the date of the journal.

The Appendices

Appendices give detailed explanation of methods and techniques summarised in the main text together with supplementary matter which it would not be appropriate to include in the main body of the text. Appendices should be labelled (eg. Appendix A. Derivation of Quantum Eq. 1).

References

1. M. Markel, Writing in the Technical Fields, IEEE Press, 1994.
2. R.A. Day, How to Write & Publish a Scientific Paper, Oryx Press, 1994, 4th edition.
3. H.B. Michaelson, How to Write & Publish Engineering Papers and Reports, Oryx Press, 1990.
4. T.N. Huckin and L.A. Olsen, Technical Writing & Professional Communication for Nonnative Speakers of English, McGraw-Hill, 1991, 2nd edition.
5. A.M. Wilkinson, The Scientist's Handbook for Writing Papers and Dissertations, Prentice Hall, 1991.
6. T.A. Jordan and C.J. Andrews, Writing Technical English: A Course of Instruction and Coded Correctness, Department of Electrical and Computer Engineering, The University of Queensland, 1990.