Whenever you write a document intended for someone else to read, you are trying to communicate something to somebody for some purpose. The document might be a report of work done, a proposal of work to do, an examination answer, or any one of an enormous range of literary or sub-literary forms; the person who has to read it might understand the subject matter of the document better than you do, or worse; you might be trying to inform, persuade, or simply record. All these factors, and many others, have some bearing on how you should present the document, and, all too often, they are ignored.
This is a document. In it, I, the author, am trying to communicate to you, the reader, some ideas about writing documents effectively. My immediate purpose is to convince you that it's worth taking a little trouble to produce something that does in fact convey the message which you intended; in the longer term, I hope that the result will be that I shall be able to understand at first reading a larger proportion of students' work submitted for my perusal. Because of this special bias, I'll often assume that the document is an assignment report, or a project report, or a thesis. In a few places, this assumption will be significant, but many of the principles I shall put forward are equally applicable to any form of written communication.
In the rest of this document, I suggest some guidelines which might help you to avoid some of the pitfalls which lie in the writer's path, but these can only be generalisations, and need adapting to suit particular circumstances. The important thing is always to remember what you are trying to do, and to try to put yourself in the place of the intended recipient; then ask yourself, "What is the best way of getting the message across to me ?". Then do it.
So that's what I've done, and this is the result. Here goes.
Are you trying to describe something ? Or to impress the reader with your intelligence ? Or to persuade someone to do something for you ? The answer to this question goes a long way to determining how you present the document.
NOTE WELL that I am not advocating any distortion of the truth, nor even biased selection; but it is quite possible, and might well be justifiable, to present a record of total failure in such a way as to make it clear that, at every stage of events, and after careful consideration, you took the best available course of action. It is equally possible to present the same chronicle of events in such terms as to invite instant dismissal, so it's worth taking some care.
The difference appears in the emphasis in the document on things, people, actions, places, and other entities which appear. An instruction manual for a machine is a clear but rather colourless document, in which the machine takes first place, and people only exist to push buttons or move things about; the feelings of the people, and the brilliance of the equipment's designer, are not germane to the object of the document. In contrast, you, the writer, and your good qualities will be more in evidence if your document is intended to impress people in your favour, while the reader and the benefits which will follow from the desired course of action will be more prominent if the object is to try to persuade someone to do something. Discretion is, of course, all : any appearance of over-emphasis can be counter-productive. At the same time, it is well to bear in mind that an examiner ( usually ) really does want to be convinced of your intelligence; so ( usually ) does the employer, though you might need to be more careful with timing.
How you make this decision depends on the circumstances. There are two major cases:
This is almost as important as the second decision. There are three reasons for not including material in a document :
There are three things to consider here:
It is also worth bearing in mind that it is far easier to be ( or, at least, appear to be ) formal, brisk, and efficient, and still be effective; it is much harder to produce a report which is happy, chatty, and CLEAR. But avoid extremes : if I get a letter which says: "In re yours of 5th inst, I beg to advise that said goods are now available", I assume that the writer is a cretin.
Generally speaking, some form of the conventional tree structure - chapters, sections, paragraphs - seems to work best, if only because a document organised this way can be read through from beginning to end. Other structures - the directed graph of programmed learning texts, and the matrix of the Informal Introduction to Algol 68 - seem to me to be less effective. Whatever you choose, it should be well signposted : each heading should indicate its level, either by a hierarchy of numbers ( "paragraph 3.45.7.3" - useful if you refer to them a lot, but not otherwise ), or by typeface ( capital or lower case, underlined or not, etc. ); and a table of contents can be useful even with quite a short report. Notice, by the way, that a table of contents is a list of chapters, paragraphs, and such in the order in which they appear, and is conventionally found at the front of the text; an index is an alphabetically ordered list of keywords with the page numbers on which they occur, and is conventionally found at the back.
It might also be helpful if some indication of the structure appears at the head of each page - for example, the paragraph number. Make sure that it will be helpful before you do it, though, as too much clutter is distracting. It goes without saying that any document with more than one page should have page numbers.
It is frequently the case that different tools are appropriate to different parts of a document. There is nothing wrong with this, provided that all the parts fit together into a coherent whole.
One thing to watch if you use both text and diagrams is the disposition of the diagrams with respect to the text. Ideally, each diagram should appear on the same page as the text which refers to it ( or on the opposite page, if that is possible ). References to diagrams on distant pages ( especially those which refer to "FIGURE 45" without giving the page number ) do not help the reader. If a diagram is frequently referred to, of course, it might be impossible to avoid some page turning, but a little thought can often reduce the load on the reader considerably.
You can control the emphasis on different parts of a document in lots of ways. You can commonly vary the spacing between lines, or between c h a r a c t e r s, use CAPITALS or lower-case, underlining, bold or italic characters, indent text at one or both sides, and change the appearance of the printed material in many other ways. With more elaborate machinery ( such as a Laserprinter ) much more variety is available. As is frequently the case, over-indulgence in these techniques is unwise, but their judicious application can turn many a sow's ear into at least a plastic purse.
If you've reached this point, you know what the document is for, you know what you want to put in and leave out, you know the style you will use. The main omission is the decision on how you are going to put it all together, to use the structure to express the material so that the document serves its purpose.
This is a matter of grouping and sequence. In an instruction manual, you would group the material using purely technical considerations - a section on specifications, a section on operating instructions, a section on fault diagnosis, and so on. This is not necessarily the best organisation if you are trying to be persuasive; you might wish to begin with a few heart-rending case studies, then put forward your proposal, then other proposals, together with your assessment of their merits. If you want to show how clever you are, you might choose to lay great stress on why things are as they are, presenting a sequence of observations together with their interpretations.
There are perhaps as many ways of arranging your material as there are things you want to say about it, but do realise that the order is important, and give it some thought. The main consideration is always that the finished document should be easy to use for its intended application.
But start with a ROUGH COPY. At this stage, you might feel that you've already done enough planning to finish the thing off blindfold, but any such feeling is delusory. In fact, even before you start your rough copy, you should plan the outlines with even rougher notes - which will probably demonstrate that some of your clever ideas under 1, 2, 3, 4, and 5 won't work. If so, don't try too hard to save them, or you end up with paragraphs which are all too obviously twisted to fit their headings, and other such monstrosities. You should be prepared, indeed, to scrap all you've done and start again - but if you've been reasonably careful, most of your preliminaries should stand up to the light of day.
Finally, when you make your good copy, take some care with neat layout, spelling, grammar, and punctuation. These might be bourgeois claptrap, but they are nevertheless very powerful aids to reliable communication. Perhaps we cannot all aspire to effortless and effective use of the written word, but we can all take pains with obvious things like leaving enough space between lines, referring to a dictionary in cases of doubt, and - if you can't manage the grammar and punctuation for yourself - ( a ) getting a literate friend to look it over, and ( b ) resolving to find out about grammar and punctuation. ( Notice "dictionary". A spelling checker will usually make sure that everything in your document which looks like a word really is a word - perhaps in the USA - but it won't make sure that it's the right word. )
Most people find that this step is necessary, because you can only effectively check the layout on the printed copy. This isn't easy to do on the screen, even if you have a big one and your software purports to show you what the pages will look like. Little things to check are margins ( on all four sides ), type faces and type sizes all the way through, and indenting as appropriate. Look for overcrowding - a page is much easier to read if the layout is obvious at a glance, and that usually means there has to be enough white space around the text to make headings stand out, to give clear separations between paragraphs, to set out any equations or other similar items clearly. Rather less simple things to check are whether page boundaries come at sensible places, whether the page numbers are right ( particularly any references to page numbers within the text - not forgetting the contents and index ), and whether diagrams fit in properly.
It is surprising how easy it is to write things which you didn't mean to write; it is also possible to be vague, misleading, confusing, and simply wrong quite unintentionally. While you should look out for lapses like this at all stages of the composition, they are easiest to see in a good copy. You might have to get it redone - but it might well be worth it.
( There's an official party line on this, as pushed by the university. It might give you some information about the physical form of the thesis, but we don't always take it too literally. Even so, if you want to depart significantly from it, perhaps we should talk about it. )
The principles above are fairly general, and to fit them to research reports of any sort you have to set values for some of the parameters. Here are some appropriate values.
Apart from the organisation of the technical material, there are techniques related to good use of English. Unless you are constrained to do otherwise ( some journals still insist on it ), avoid the third person passive construction - "The experiment was performed ... it was found that ...". Try "I performed the experiment ... the results were ... ". The passive is occasionally useful to add a little variety, but too much of it drags dreadfully. Unduly long sentences are not very readable, but a long account composed only of simple sentences tends not to run smoothly. Avoid long or unusual words unless you are sure that they're just right.
How else can you brighten up your text ? You can ask rhetorical questions, as in the previous sentence. You can try humour - but VERY cautiously. I don't know any reliable rules, except "If in doubt, don't". Understatement is certainly better than overemphasis. You can try wry remarks about material which is already present in the document, but it's probably inadvisable to drag in additional material purely for the sake of the joke. Maintain the high intellectual tone ( should there be any ) throughout; go for wit, not slapstick.
Now all you have to do is put all that into practice. An algorithm which covers quite a bit of the ground is :
Writeabout( your topic ).
Writeabout( aim ) :
statement of aim.
analysis of aim.
for each way of achieving the aim
list good and bad features.
Choose the best way.
With the best way
for each step in the way
Writeabout( step ).
Don't take it too literally; but keep the principles in mind, and you won't go far wrong.
In deciding HOW TO PRESENT IT, bear in mind the two purposes of the document. So far as assessing your report or thesis is concerned, examiners aren't ( much ) interested in what you've done. It is far more important that they should be convinced that you know WHY you have done that particular thing out of the many possible things you could have done. The moral :
There are about three ways to justify an assertion :
Another thing about examiners is that they have to READ the document; help them to do so. I've already mentioned some points under the TONE heading. Generally, your presentation should be closer to that of a novel than a technical manual. Emphasise the logical development of your work ( which is not necessarily the same as its chronological development ). Each sentence should build a little onto the reader's knowledge of what you're trying to say, so you should usually avoid forward references, and make backward links clear so that the steady development is obvious. Some forward references can be helpful if they explain why you are doing something, and prepare for later backward links; the bad ones are those which make it impossible to understand chapter 2 until you've read chapter 6.
I am not really sufficiently naive to believe that these notes will lead to an immediate and dramatic improvement in the standard of students' written work. Neither do I imagine that the approach outlined here will instantly be received with glad cries by all who read it.
But I do believe that if some who read this document are moved to spend a little time thinking about and analysing their own efforts at written communications, then they might be able to decide to adopt some similar principles for themselves. If I argue from the position that all students are intelligent, then I can't lose : either this document will be completely convincing, and will therefore serve its purpose; or the intelligent students will analyse its defects, and thereby come to understand the true principles of report writing, which was, again, the object of the exercise. ( It follows that, if the standard of the submitted work does not immediately rise, then I can draw certain conclusions about the intelligence of students. )
Think about it.
Alan Creak,
February, 1997.
The first version of this document was written in 1979, for the benefit of students taking courses in Computer Studies. That was a long time ago - so long, in fact, that the word "he" and its derivatives ( like "his" and "him" ) was frequently used in the document. At that time, the word "he" was widely understood as a third person singular pronoun which, in the appropriate contexts, took common gender.
For reasons which we shall not pursue here, that is no longer the case. I am far from happy about the change; but I have no wish to cause people distress. If you inspect the document, you will find that the supposedly offending word does not appear. ( Except in this Post Script. )
Did you notice that as you read through ? I hope not; because I have been to a little trouble to make such changes as were needed while maintaining what I believe to be good English style. So you will not find any offensive repetitions of phrases like "he or she" - or, even worse, non-words like "s/he" - or, worst of all, plural pronouns used in singular contexts, usually with totally inappropriate matching verbs.
There are two morals. First, there is nothing to be gained by writing things in ways which other people find offensive, however stupid their attitudes might seem to you. Second, it can be done without descending to the level of semi-literate jargon which nowadays passes for communication among supposedly intelligent self-styled "liberal" people.
This revision has been occasioned by the advances of technology : I have removed references to typewriters and hand-written reports. I have also tidied up a few loose ends, made a few corrections, and added a few details of which a selection of Project and Thesis students didn't seem to be aware; further suggestions for inclusion are always welcome.
Tidying up, clarification, one or two additional points. ( And correcting some spelling mistakes, but don't tell anyone. )
Well, this time I decided that I was converted to electronics, so everything moved to WWW. This might yet prove to be a mistake.