Verity is the pseudonym of a programmer based in the UK. She can be contacted at [email protected].
I have finished all the programming. Like a Good Girl, I have put the source into version control. And I have even — do stop smirking or it will stick — done some testing. There is nowhere else to go now but down into Documentation Dell, Dakota. I'll get started in a moment or two, as soon as I can think what to put. Any second now.
And I bet I know what you are thinking. You think that I am one of those slapdash manual writers. You think that I make a few screen grabs, plonk them into the document bish bash bosh and then ladle in some of that oh-so-lazy descriptive text that is produced mostly by those productive keystrokes Ctrl-C and Ctrl-V. You know, the kind of thing that takes bilious restatement of nothing and places it in sentences of intestinal entanglement:
Figure 3.2 shows the "ID Entry" dialog. Below the edit field for your name, marked "Name," is an edit field for the first line of your address, marked "Address." The "Tab" key should be pressed, or the mouse clicked in the appropriate area of the screen, to move between the edit fields. Below the "Address" edit field is an edit field for the second line of your address, which is unmarked and obviously should be left blank if your address does not have a second line before the "City" edit field. The "City" edit field, which may be the second line of your address as written but is always the third edit field in the "ID Entry" dialog, is where you should type in the name of the city where you live, if you live in a city. The "Tab" key should be pressed, or the mouse clicked in the appropriate area of the screen, to move from the unmarked "Address" field to the "City" field. Obviously, if you don't live in a city, you should leave the "City" edit field blank...
This may be what you think, but you are wrong. My manuals are genuinely lovely. True, I do like to use an occasional screen dump, but only if the action demands it. As for my accompanying prose, it was not for nothing that I came in third in English Composition two terms running in Form 3b. (I would have come in second if I had overcome my predilection for using "whilst" instead of the less pretentious "while.") Miss Jones herself, my erstwhilst Form 3b teacher, would surely bear witness to the dainty elegance of my descriptive writing. The problem is that she was pretty well the last person to read it. It is fairly certain that none of our customers ever do. [Now go away and stop bothering me. Perhaps it would be easier if I started with the index? No, that's silly.]
A case in point. Only last month, I was giving phone to a certain yokel who had come unstuck with one of my apps, and after listening to his pithy statement of the case (Actual quote: "When I clicked the mouse it sort of went blue all over, then faded away"), I realised that what he wanted to know was set out in loving detail in Section 2.3.
"But this is all in the manual!" I cried. "I've written up this situation exactly!"
"Oh, I can't be doing with manuals written by the programmer," replied the cheerful rustic, completely unaware of his mortal danger. "I keep 'em locked up in the cabinet, where they can't do no harm."
It was lucky for him that he was on the phone, because had we been face to face I doubt that I could have controlled my second set of jaws. (You know, the ones that, at time of stress, have a tendency to emerge from within my throat and, before you can say "Sigourney Weaver," bite off a head.) [Do you think it's OK to begin a technical reference "We deem it self evident"? Really? Oh.]
And it's so unfair, because some manuals do get read. A long time ago I used to work with a programmer named Eric, who thought that wordy descriptions, pictures, and mixed case were all for wusses. And although Eric's manuals gave me headache just looking at them, the customer used to pore over them with eye-popping intensity. Their style seemed familiar:
CLICKING "SHORTCUT" ONCE LIGHTS SHORTCUT FEATURE, SKILL SHOT CLICKING TWICE ("DOUBLECLICK") LAUNCHES PROGRAM.
HITTING "FILE" "SAVE AS" SEQUENCE DISPLAYS DIALOG FOR RENAME / MOVE DOCUMENT OPPORTUNITY. TYPING PATHNAME OR CLICKING FOLDER COMPLETES.
DRAGGING FOCUS CONTROL CAUSES "SPECIAL" LIGHTS DROP TARGETS FOR INTER-CONTROL DATA TRANSFER MODE.
NO TILTING
Mind you, Eric didn't feather bed his users with interface trinkets such as logical layout or consistent behaviour. Combine this with a strong regional accent that made his spoken voice incomprehensible and it's easy to see why customers read his manuals. They had nowhere else to go. [How about it if I put in an "Overview"? Then I can drop in a dirty great schematic diagram, and use the making of that as cover for spending a few of happy hours playing with those cute little Visio stencils. I just love that Internet "cloud" shape. It makes me laugh every time.]
Thinking about it a bit more, I wonder if I am not being naïve. The only reason I am doing a manual is because of contractual obligation. The only reason it got in the contract is because the salesperson thought it would make the sale easier. The customer would probably be just as happy with a piece of wood with the word "Manual" printed on the outside. Hmmm.
Clear out the clipboard and get the "Print Screen" key warmed up, would you? I've got some screen grabbing to do!
DDJ
