The prime purpose of technical documents is to convey correct information efficiently and clearly. However, documents written by non-specialist authors often display features which, we believe, decrease this efficiency. Also, most authors type their own text, so various filters that cleaned raw text in the past (like fussy typists and obsessive editors) have been bypassed. The result has been an epidemic of document diseases which makes life harder for the reader. Here are some that we come across:
The most common fault in writing. It is an insidious disease which afflicts us all, but it can be controlled if you look for it. There is far too much to read without having to wade through redundant waffle. Good documents should be short and concise. Get to the point! A reader does not want to waste his time ploughing through:
The purpose of this document is to introduce the reader to the CHART software system which has been developed to facilitate the production of finding charts which, hopefully, will be of some assistance to the user’s astronomical investigations.
when he would be quite satisfied with:
This program produces star finding charts.
Authors sometimes get so wrapped up in their work that they cannot conceive of anyone not being au fait with what they are writing about. Don’t just write for members of your clique, but give outsiders some background and context to your work. Also, a brief introduction is very useful for me when I am adding notes on new software to SUN/1.
Believe it or not, people sometimes omit to describe how to start up their software, or they may bury this information in the middle of a big paragraph. Put this information near the front and make it clear, e.g.:
Most people accept the convention of leaving a space between individual words as they recognise that it helps the reader. However, the convention of leaving a space between sentences and after punctuation marks is under attack. One now sees text written like this:
I can save my precious time,and energy,by missing out unnecessary spaces;anyway,I’m impatient.I don’t care if this makes my text irritating to read,and infuriating to edit,as my time is more important than yours,and this extra speed gives me a competitive edge.
This style of punctuation might be tolerable in a Fortran FORMAT statement (where, perhaps, it originated), but it is barbaric and illiterate in text meant for the human eye.
This is the inverse of the Smothered punctuation marks disease – too much space rather than too little. It has the following symptom:
Some authors ( not many ) do this.
No doubt, such authors think this is clearer than:
Most (thank goodness) do this.
The problem with this disease is that it makes the syntactic structure of a sentence less obvious – you are writing for the human eye, not a parser. Moreover, unless you go to special trouble, odd parentheses will stray onto the previous or next line.
The trouble with tabs is that they may not be interpreted as you expect, since this depends on the device or software your reader is using. What you see on your terminal may not be what he sees on his. The safest thing is not to use them.
A common disease of TEX virtuosi is to submit document files which refer to other files which only exist in their author’s local environment. Make sure you submit all the files required for someone else to produce hardcopy.
Many text processors have a facility to generate today’s date automatically. This can be very convenient in things like letter headings which are used to produce a single document at a specific moment, but it is dangerous in long-life source documents that may generate hardcopy several times. A date should identify such a document uniquely and should not be vulnerable to arbitrary change. The use of clever dates can cause a number of versions of a document to go into circulation which are identical, apart from the date in the heading. This can cause great confusion.
The World Wide Web is a popular tool for publishing information, and Starlink uses it extensively. The enormous amount of material on the web and the arrival of commercial pages has led to a competitive striving for attention by its information providers. This has not always been to the advantage of the reader, as there is sometimes a conflict between attracting a reader to your text, and making that text easy to read. Three forms of attention-seeking have spread across the web like cane toads in Queensland. We believe they compromise legibility:
Text is often presented against a background image. The intention is to make the page look attractive and encourage people to read it. This technique may work when used with discretion in high-quality publications printed on glossy paper, but we feel it doesn’t work successfully on computer terminals. The reason is that most computer displays have much lower resolution and dynamic range than glossy paper, so a background image seriously degrades the legibility of the foreground text. Another problem is that some browsing software just can’t handle background images properly. If you use background images your text may become illegible (and your writing efforts futile).
You don’t have to use background images to make your reader abandon an attempt to read what you have written. This can also be achieved by extrovert choices of colour for text and background, and also by using fancy fonts.
You can draw attention to the latest or most important information on your web page by repeatedly flashing it on and off. The effect on at least some readers is similar to that produced by those car alarms that go off in the car park next to your office window. The problem is the same: you can’t turn the message off once you’ve got the point. It then becomes distracting and merely adds to the ambient noise.
No doubt when we all have multi-media terminals, information will be accompanied by exciting background music and stimulating drum beats. We are not looking forward to it.