 The magazine of the Melbourne PC User Group By Their Own Hand Major Keary |
 |
We all come across examples of bad documentation; user manuals are notorious for obtuse, confusing, and poorly-written material. There is a trend towards improvement, and some manufacturers, such as Hewlett-Packard and Unisys, ask users to evaluate their manuals. They glue proper resources to their technical writers who are not just engineers burdened with an add-on duty.
Unfortunately, many software houses and hardware manufacturers still perceive documentation as the place where economies can first be achieved.
By way of reminding those responsible for documentation budgets that users notice and resent poor manuals - and at the same time providing some entertainment for ourselves - readers are invited to submit their favourite examples.
But It's Not Just Them
I probably read more documentation than most computer users, and certainly see some examples of sloppy, poorly organised, and badly written copy that should never have been allowed through the mail.
Our own contributors include many who know their particular subject, but who have not developed writing skills. Generally their material is organised in a reasonable way, which lends it to uncomplicated sub-editing.
Some, however, fall far short of that. For example, the following spelling caused a checker to crash, irretrievably brain-damaged; if it had been someone in a bank at hold-up time even trauma counselling (that great Australian invention) would be of no avail:
|
simerley re-organies bennift multable. |
And, from another contributor, how about this:
| "When I first described this technique a rude-mannered, snide individual wrote a letter saying I should use as it was much faster. What he was implying was that I was too thick to know that .... "I knew that perfectly well. What he had missed was that ... I knew ... ... , but I had already mentioned that, and pointed out that it is a lot easier because of ... . If there is another snide idiot out there, I am going to rub his nose in this paragraph." |
The problem is that some contributors belt away at a keyboard, save a file, and send a disk (or upload to BBS) without reading their copy first, or even running it through a spell checker. Style checking programs may not suit every situation, but they are useful for drawing an author's attention to possible problem areas.
Hobby Horses
We all have a degree of passion for some topic or other. If you want to ride your hobby horse through these pages please make it at least intelligible and, if possible, entertaining. (I know there is someone out there who is already drafting a critique of that sentence and I will be pleased to print it).
There are some esoteric subjects of interest to a limited audience; PC Update is one of the few general computer publications where that kind of material is printed. However, authors should either have a track record for accuracy and the capacity for lucid writing, or they should find someone willing to check the manuscript.
I do not class something as hobby horse writing just because it is esoteric or about a subject that requires some special knowledge. It does us all good to be exposed to unfamiliar
subjects - a kind of diploma to add to that degree (B.HKn) from the university of hard knocks.
Collaboration
If you have something worth saying, but feel a lack of confidence in being able to get it into words, consider collaboration. There is no reason why an article should not carry the names of two, or even more, authors. Academics do it, so why shouldn't we?
I am sure the quality of PC Update's content would be improved. It would certainly ease the
editorial burden, not to mention giving some acknowledgment to those who quietly improve, or even transform, contributions.
Back to the Pros
Those who are paid to produce documentation have no excuse. I have some examples, printed below, and am sure
PC Update's readers can contribute many more.
While it is not intended to crusade, or even ride a hobby horse, there is a need to remind
manufacturers and software publishers that manuals should be user friendly.
From the manual accompanying Reflection, a graphics conversion program:
"The default settings are heuristically modified by Reflection."
This is from an expensive book on hypertext, written by academics:
"Convenient reference following only begins to exploit the power of a hypertext system." (There is, in fact, a simple solution to making the sentence mean something, but why should such texts become an obstacle course?)
Below is a typographical marvel from the same work.
10.2 REQUIREMENTSOFTECHNICALDOCUJMENTATION SYSTEMS
|
My favourite is from an Epson printer
manual:
"To find nl and n2, first calculate the displacement required (n dots) and then, if it is to the left, subtract it from 65536. The values of nl and n2 can the be calculated from the formulae:
n1 = MOD 256 n2 = INT (n/256). |
Reprinted from the Jan / Feb 1993 issue of PC Update, the magazine of Melbourne PC User Group, Australia
