Date: Wed, 3 May 2000 16:14:59 +0100 (BST)
From: Stephan Weiss <sw1@ecs.soton.ac.uk>
To: elug2-all@ecs.soton.ac.uk, ceug2-all@ecs.soton.ac.uk
Subject: D2 --- feedback on report writing

Dear D2-project students:

following the correction of your lab reports for D2, I would like to
give you some general feedback. As this was your first project with a
jointly submitted report, maybe even your first larger report at all,
some comments regarding the structure and the style of writing appear
to be appropriate.


STRUCTURE:

The structure should feature an introduction, sections where the project
is explained, and finish with conclusions and a list of references. Some
general guidelines are (not binding, but good practise):

* Introduction: this should 
	- set out the problem and its motivation; 
	- give an overview over the solution and its steps;
	- overview the organisation of the report.

* Report Chapters: should be
	- divided into sensible sections, subsection, etc. with 
	    sufficient guidance for the reader to keep track of the
            overall aim;
	- the report should be self-contained, i.e. only additional,
	    for the general understanding unneccessary information 
            should be included into appendices.

* Conclusions: should
	- summarise the problem and its solution;
	- state how well the aims have been achieved;
	- give an outlook on what could be improved / added (technically!)

Introduction and conclusions are the most important part of a report;
if time is short for reading, this is what will be read, and will
hence determine how the work is judged, or whether the reader is
sufficiently motivated to read on after the introduction! 

Page numbers and section numbers help for better referencing within
the report.


WRITING STYLE:

* An argumentative style of writing is always preferable to being
  narrative. A bit exagerated: "first we did this, then we did that"
  should rather be "Because of ..., we proceeded with ...". The
  flow of arguments is very important.

* Avoid 1st person as best as possible.

* Informal language should not be in a report. The most obvious are
  don't, doesn't, can't, etc, which should always be fully written
  out (do not, does not cannot, etc.).

* Humour is helpful but should be kept low, and if used, be
  subtle. "Our circuit was a big long spaghetti" is too informal
  and even "data was written to a human readable file" is maybe
  questionable.

* Figures and block diagrams are very helpful to support explanations in
  a report, and are a lot easier to understand than long columns of text.
  
* However, figures must be properly referenced and explained from within 
  the text!
 
* Using shortcuts (like ULA, FSU, etc) is good, but these should be 
  introduced explicitly somewhere in the text prior to using them, e.g.
  " ... frame alignment word (FAW) ... ".
 

GENERAL:

* Although written by a number of people, the report should read as
  from one mould.

* Content should be strictly technical. Comments within the report on 
  e.g. the team work or remarks such as "Team members had steep learning
  curves."; "This was very difficult." or excessively blaming "external 
  forces" for set-backs in the project should be avoided.
  (Comments on team work should in this case have been restricted to 
   the appendix section on "team management" that specifically had been
   asked for.)


Hope this feedback provides some help for you. Some reports were actually 
of excellent quality!

Regards ... Stephan

----------------------------------------------------------------------
Stephan Weiss		                    Tel. : ++44 (0)2380 597645
Dept of Electronics & Computer Science      Fax. : ++44 (0)2380 594508 
University of Southampton                   Email: sw1@ecs.soton.ac.uk
Southampton S017 1BJ, UK      URL: www.ecs.soton.ac.uk/info/people/sw1