Technical books, manuals and instructions can be extremely difficult to read (and yes, I know that they can also be very difficult to write!). In fact it seems to be a standing joke that nobody ever reads the manual! So there seems to be a tend to make manuals shorter - presumably on the theory that a shorter manual is more likely to get read! Unfortunately, shortening a manual also makes them more terse and less readable. So we have here a distinct problem!
Now 'readability' is not an absolute. Different people like to read different styles. It surely is not possible to write anything which all people will like to read - so we're looking for a compromise, a 'majority opinion'.
For a technical manual, that compromise has to be defined as 'that point which will cause least confusion and misunderstanding from the users'. The point where there is least after-sales (and for that matter, pre-sales) technical support work. If the work is also used as a sales aid, then this slightly modifies the description!
Such a point is hardly possible to even measure! In fact it isn't actually a point but an area - probably something like a 'bathtub' curve, rising at each end. Make the manual too simple and problems occur because to many people skip bits of it. Make it too technical other people won't even start to read it.
I realised long ago that there are some (many) people who simply won't read a manual at all (for whatever reason). If they aren't going to read it, then, no matter what I write, I am never going to please them! So I start writing with the assumption that the people I'm writing for do actually want to read what I write. So I need to express myself clearly, in a readable style, but without too much 'flowery' language which will not be to everyone's taste. A little humour - yes. But I try to keep the style plain and simple.
I must assume that the people I write for are not as knowledgeable as I (or else I should not be writing the manual). So I try not to assume too much specialist knowledge. But I have to assume some! I have to guess roughly from where the majority of my readers are starting out. It's a very difficult balance! Also, I try not to use ambiguous words. I try also not to use to use the same word to describe slightly different things! Language can be inexact: it's usually clear what we mean by the context. But when the subject is new to the reader, he has no 'context' so words which are not used precisely will add to the confusion! If I'm going to ascribe a particular meaning to a word - for instance, if that word is a 'menu' entry on a computer user interface - then I try to pre-define clearly and exactly what I intend the word to mean and I try not to use that word for anything else! This is a difficult balance, since if I do re-use the word I will know exactly what I mean and it is difficult to remember that I've already defined a special use for that word!
In the late 80's I was divorced: I had to sell the family home and decided that I'd do my own conveyancing. It wasn't at all difficult so, when I remarried, my new wife and I decided to do our own conveyancing when we purchased our new house.
So, knowing that buying was more onerous than selling, we purchased a book on the subject, the 'Which guide to buying a house' if I recall correctly. It proved to be as technical and indigestible as any computer manual! So we looked for other books and eventually found a book called 'The legal side of buying a house' by Michael Josephs. It was actually slightly smaller than the 'Which' book.
This book (unlike computer manuals) did not start by telling you what to do. It started off anecdotally by explaining how the house conveyancing system had arisen, how silly and illogical it all was, and how most of the legal bits actually did nothing useful at all except line the solicitor's pockets. The book actually made interesting reading! This went on for about two thirds of the book. The last third (only) was about how to actually do the conveyancing. But the instructions were now very easy to understand, because the introduction had done a very good job of smoothing out the learning curve.
As it happened, we did have to use a solicitor, not because it was difficult but because we were using a building society and they simply didn't like DIY conveyancing! Their solicitor kept on finding more searches that we had to do, searches which I'm sure no other solicitor would have been asked to do. But I digress!
So, here was a subject as technical as any, where instructions could be written indigestibly - or in an easy-to-read and clear fashion.
Can this philosophy be applied to computer manuals? Certainly very few of them are currently at all digestible or easy to read!
As I see it, there are three uses for manuals:
It would seem that these three requirements are mutually contradictory. Yet I am not certain of that! Very difficult to reconcile all three - yes, but I suspect not impossible.
The jackpot question, this one!
However I suspect one answer is simpler than most people might think! A program is good when it does what I expect it to do in the way that I expect!
As far as I can see the only possible way of accomplishing this is to introduce the new user gently to the program! And that doesn't mean sitting him down in front of the computer and making him wade through a tutorial! It means writing a friendly introduction to the program - which the user is free to read before he gets the program! By the time he's read your brilliant intro, he knows what to expect and is drooling with anticipation!
It's an area where few authors succeed - or even try. But, if a prospective user of your program doesn't know what it's going to do, why should he even look at it? To use a program, most users need some sort of reason! There are simply too many free programs for them to play with! If they are going to look at your program they need to know what to expect. You, the programmer, are probably the only person who can describe your program. So do yourself a favour and give your prospective users the respect they deserve by at least trying to tell them what to expect!
Of course I don't pretend that writing a good intro is at all easy. But you should surely try.
PipeDream is a splendid program, part spreadsheet, part text processor, part database. It is programmable. It has so many key presses defined in so many obscure ways that it is perceived by many as being very difficult to learn. Yet I have no problem with it. However, I am sure that, it I came to it fresh today as a new user, I would find it very difficult indeed. The reason is based in history: PipeDream has a long history. On the BBC micro, in the 1980s, there were three programs: View (a word-processor) ViewStore (a database) and ViewSheet (a spreadsheet). I owned and used all three extensively. They were all written by the same author - Mark Colton.
Then ColtonSoft released another program for the BBC. Called View Professional, it effectively amalgamated the three View programs. The same program was the core software supplied with an early Sinclair computer, where is was called PipeDream.
Then the 32 bit Acorn Archimedes computer was released. Soon after that PipeDream was released for the Archimedes. I got a copy. It was upgraded - PipeDream 2, 3 and now PipeDream 4. I followed the upgrades, learning as I went.
This 'growing with the program' is what, I think, most users do. It gives them a continuity and a way of learning a difficult and complex program. This growth also makes it difficult for the user to swap to a different program. It also makes the program much more difficult to learn, as it evolves!
The BBC master has a second processor that would run IBM programs. I had one of these as I thought that there must be greener grass out there (I soon learnt there wasn't!). One of the programs I got hold of was dBase 3. This was the 'top of the market' spreadsheet for IBM compats.
The manual was unreadable - far less digestible than any Acorn manual I have yet read! I saw a large learning curve ahead, with little or no visible reward. This made it difficult for me to want to read the manual!
Then my employer found me a not-very-modern Apricot computer. It was an IBM compat, with Apricot's own front end and some 'adapted' software. The front-end wasn't bad, as far as it went (which was not very far), but the computer had a spreadsheet in it. That spreadsheet was dBase2! It wasn't very difficult to learn.
Of course having learnt dBase2, the step to dBase 3 wasn't then huge, so I advanced easily. I used dBase 3 for a couple of years and quite got used to it.
Then I bought an Archimedes computer, and a copy of PipeDream.
It felt like I had come home again!
!Prophet is an accounting package, available only on RiscOS computers. It's widely liked by all who use it and I don't think I've ever seen a bad thing said about it or it's author, Quentin Paine. Actually Prophet on its own is a very adequate reason for owning a RiscOS computer, even if you use the computer for nothing else! It is said to be a match for anything available on any other platform.
When I first had Prophet I really had little difficulty actually operating it. After all RiscOS is about a unified, easy to operate, friendly and 'intuitive' operating system for all programs. Any program written for RiscOS should be almost obvious in its use - provided you've got a clear understanding of what the program's actually designed to do! But with Prophet, what I didn't understand was the accounting bit. I'm an electronics engineer cum technical author, not an accountant! So I told Quentin that it needed an introduction, not about the program itself, but about the accounting. He promptly wrote such an intro and apparently it was widely appreciated.
Once you understand the accounting bit, it becomes pretty clear what the program's for and therefore how to operate it. It's a versatile program, so of course has plenty of depths, and some sort of reference guide is indeed required for these.
RiscOS abounds with very good PD programs. Many people use RiscOS because they enjoy programming. There are many programmers who, by day, earn their living running networks of IBM compats and, for relaxation, write programs for RiscOS. So the quality of programs is undeniably high.
There is a HUGE problem however. Apart from the fact that some good programmers have amazingly poor language skills and the fact that the programmer is usually far too close to the product to be able to describe how to operate it properly, no PD program that I have ever seen has an adequate description of exactly what it is written to do and exactly why I should use it! There are so many PD programs that if I'm to investigate one, I really need a good description of what its purpose to convince me that the program is worth investigating!
Programmers seem to write a program, then write instructions on how to use it, and instructions clarifying the operation of various bits. But the first thing that I need when I pick up a new program is a good understanding of exactly what the program is useful for, why it was written and what it is likely to do for me! I believe this require a short 'essay' on the program not explaining how to use it, not getting technical but introducing it!
Such an Essay also should, I believe, be written for all commercial programs also. Not only would it act as an introduction to the program, but it would also act as an extremely valuable sales aid. After all, if the software house wants my money, surely they should make some effort to convince me that the program will be useful to me! Or do they all expect me to part with my money 'on spec' without any proper idea of what I'm buying just for the privilege of experimenting?
But isn't that the whole purpose of a review?
Maybe. But reviews cannot give more than a surface coverage. Few reviewers can get into depths on a program's features. Modern programs are far too complicated for that. Indeed, the introduction I am advocating cannot itself go into too much depth, but if I am told the sort of problems the program is intended to solve and the perceived market gap it is designed to fill, then I will have a very good idea. Anyway, I suspect that any software house writing their own intro would want to make a point about the 'frills' they were particularly proud of. That would give me a very good idea of the product's potential.
I'm not suggesting that this introduction would be a universal panacea. But I am suggesting it would make the program sell better and be a lot more friendly!
Without doubt technophobia is increasing. The modern world is getting more complicated. Computers are at the fore-front of such advancing complication! Eventually artificial intelligence and voice recognition will solve the problem by allowing the computer to operate the human: in the future, computers will take guesses as to what the human wants, they will ask for clarification of ambiguities and they will offer choices to the human. But we're a long way from 'Star Trek' yet. Computers are still frightening to most people. If MicroSoft have their way, computers will remain frightening as fear is one of the things that makes users stick with the devil they know!
There's nothing more frightening that to be dumped straight into a computer manual with no clear idea of where you're going, or what you may find on the way! One problem is that, once technophobia has set in, it is a positive feedback mechanism. A manual, once perceived as being unfriendly, won't get used properly and the even good bits won't be noticed. A vicious circle has started and is difficult to break. Such a situation is frustrating to all concerned, the software author - the user and technical support, who are sorely tempted to say RTFM!
In any social encounter, we are always uneasy meeting new people. When we introduce a friend to a stranger, politeness demands that we introduce them first. If we know, before hand, that our friend is to meet a stranger, we are more likely than not to spend a considerable time talking about the new stranger, by way of a longer introduction.
That is exactly what I suggest technical manuals should do. If these introductions are important between people, how much more important they must be between a person and something as 'alien' as computer software! Most new users of software happen on that new software on their own, with no 'moral support' whatsoever. I now I need an introduction to new software. I need someone to tell me all the good things it will do, so it is a (potential) friend before I meet it, so that I am anticipating the meeting with pleasure!
I have tried to fathom many computer programs without this introduction, and many of them have purposes so alien to me, they scare me away. I am surely not alone in that! The more experience I get, the more I recognise alien, unfriendly programs before I get into them! Yes - this may be my problem, I may be anticipating problems that don't exist, but such is human nature! I believe this effect exists in most of us, to a greater or lesser extent. Probably I just happen to be more aware of it than most!
In any technical instructions certain words (and phrases) take on special meanings. So, for example the word 'filter'. We all know what it means, yet to a chemical engineer it has a meaning different than to a housewife. Similarly it has a totally different meaning to a software engineer, and then the meaning is subtly different whether he is using the word to describe an email program - or a text processor. Now the true meaning may not actually be that different between the email program and the text processor, once you get to know the word's significance. But to someone new to the instructions the fact that the word 'filter' is being used for some technical process means that it will probably have a subtly different meaning from normal, so is 'unfriendly'. The way round this is to locate such special 'reserved' words (not an easy task in itself) and to define their meaning as used in the document and to be very careful not to re-use the same word to define any other very slightly different processes!
The introduction as, proposed here, may be a good place to introduce such words, but a glossary is also good. However, the important thing is to realise that you are in fact using words which may acquire a special significance, and to control their use! Unfortunately the more familiar you are with the program, the more difficult it gets to realise that you are using such words! It's a problem exhibited by lots of instructions written by programmers.
In practise, such a list of controlled words is extremely difficult to control properly! Ideally a word used as a 'special case' should not be used for anything else, but this really isn't possible in the real world. However, the excercise of making such a list does greatly help to focus the mind of the person writing the instructions and thus helps to locate ambiguities!
This is a 'Help' utility which gives on-line help. It has proven very popular with many programmers, probably making them write instructions that they would not otherwise have written. So it is definitely beneficial. However there are probably other programmers who would have written paper manuals had StrongHelp not been available.
Of course computer manuals have their downside! One problem with StrongHelp is that it ha hypertext style links, so it can be very easy to get lost in. The other problem is that it is good for getting help on a feature which you have found in the software and for finding out more about it. However, StrongHelp is of little use in finding out the whereabouts of a feature that you know to be present! In a paper manual, you use the index for this!
StrongHelp is electronic, so has no index (you simply use the 'search; facility. But this means that programmers writing instructions do not often think about the contents of the index, which can make for sloppy writing! If there is no index, writers tend to not go through the thought necessary!
So what I would propose is that all people writing StrongHelp manuals make a list of 'special' words and put them as an index page. The user can then select the word he thinks most likely to describe the wanted feature, and search for that. This gives the required index function and also helps the writer to discipline his words in the necessary fashion.
This list of 'special' words should include almost all words used as menu entries and all words used as window names/titles.
There is a small problem with StrongHelp's search facility: it searches for words only. Entering a phrase in the search for box causes StrongHelp to search only for the first word of the phrase!
Acorn wrote a Style Guide, which sets out the desired operation of programs so that all programs should present a unified user interface to the user. Such a unified interface is extremely important, it makes new programs a lot easier to use, and this is certainly one reason why RiscOS is so much liked by its users.
Probably all programmers realise the importance of unified style. So the 'Style Guide' has, to many of them become a 'Style Bible' which shall not be broken. This is extremely silly: if all programs had the same user interface then they would all do exactly the same thing and there would only be one program!
A Guide is a guide only - not a book of natural law! Some styles are not appropriate and some programs actually benefit from breaking the recommended style, so the style guide should be treated as 'this is the recommendation, depart from it when appropriate and make sure that any departures do actually improve the program's useability'.
Of course if you are going to improve on the style guide, it makes sense to point out the fact and to explain your reasons in the intro so the departure will make the program more friendly (as you surely intended) rather than less!
There are one or two programs out there where the style has been 'improved', but the software engineer's reasoning is not apparent, so the programs become quite daunting to a new user! The learning curve must be smoothed! A friendly path up the learning curve can make climbing it a pleasure rather than a fight!