Writing User Documentation

Course outline

Copyright HCi, 1998

Week 2: Audience and task analysis

This case will be discussed in detail during the course, and a careful reading will be needed in order to allow you to discuss the contents intelligently. Students who do not demonstrate during class time that they have done the required reading and grasped the questions posed in case studies may have their course mark reduced accordingly, or may fail the course.

Before reading this case study, please make sure that you have done the reading set out in the reading list.

This case study is copyright Phil Cohen, 1998. No part of it may be copied or used in any way without the author's permission. None of the organisations or individuals named in this case are based on, or are intended to represent, real organisations or individuals.

The Managing Partner

"When the Correspondence System was first developed, we had the programmers in here for weeks getting it to work just the way we wanted it." Kingsby-Smith sipped his tea, and ate a crumb of his biscuit. He chewed meditatively, and I saw his little finger point as he lifted his cup to his mouth again. His cufflinks glowed gold, just peeping around the edge of his 3-piece pinstripe sleeve.

"Of course, as a managing partner, I was heavily involved," he said, looking seriously over the rims of his bifocals at me. "I learned a lot about computers, I can tell you. More than any other lawyer in this firm. I even," he sat back with pride, "I even learned how to connect to the world wide net using a modem. Not many in my profession need to learn how to do that."

Hungadunger and McCormack was one of the city's smaller law firms, with just under a hundred staff; half were lawyers and the other half support staff: secretaries, librarians, accountants, and so on. Four years before they had commissioned the development of a system to track incoming correspondence - letters from clients, documents from other law firms, court notices - and also to generate and mail letters written by the firm.

The system was written in C, and ran on an NT server which sat in Kingsby-Smith's office. The server was a 266MHz Pentium with a DAT drive for backups.

The Managing Partner looked after all of the administration of the firm - the closest a law firm comes to a Managing Director. He had the server installed in his office so that he could "keep an eye on it", and was concerned that all of the letters sent out by the firm were stored on it somewhere. He presumably felt that if he had the machine in his office, it was more secure. His office was certainly large enough, and a second leather-topped desk had been installed for the server's monitor. At the desk sat Colin the Systems Administrator, a small gnome-like figure who never spoke.

"Impressive, isn't it?" smirked Kingsby-Smith.

The server was linked using a thin Ethernet LAN to all of the other computers in the office, and an ISDN link gave it a permanent connection to the firm's offices in Melbourne and Brisbane.

Hungadunger and McCormack specialised in furniture law: an obscure branch of legal practice specialising in cases involving furniture. When I expressed my surprise that there was such a specialisation, Kingsby-Smith rather snootily commented that he thought much the same about people who - like me - did nothing but write software user manuals.

He had asked me to come in and write a manual for the Correspondence System because they had had a sudden increase in staff turnover - due to a sexual harassment case a large number of their secretaries had decided to leave within weeks of each other and had to be replaced. The new staff - although all legal secretaries with years of experience - had not had the advantage of working with the programmers who developed the system, and no-one had thought during the original implementation to actually write any documentation.

I thought I'd better start from the beginning, so I asked Kingsby-Smith to tell me what happened when a letter arrived at the firm.

"It's quite simply, really," he said, giving me the disturbing impression that he expected me to know all this kind of thing already. "The mail room opens the letters, and then scans them into the system. After that it's all automatic."

I asked just what was automatic.

"Well, the letter appears on the screen of one of the secretaries, who deals with it. And that's that."

It was obvious that pressure of other work had ensured that Kingsby-Smith had not had time to properly acquaint himself with the workings of the system, so I took my leave and went in search of the mail room.

The Mail Room

The Mail Room was a cosy box just behind Reception, and held two ageing women with identical hairdos. They didn't seem to be busy, so I invited myself in and started asking questions.

"What do you do when a letter arrives?"

"Well, we open it, and scan it, and after that it's all automatic," said Marge, the (only very slightly) taller of the two.

I asked her to show me, and she very obligingly picked up an unopened letter, slit it expertly along the top using a patented machine (cutting the enclosed letter into thirds in the process), tossed it to one side and took up another one. This time she opened it with a long burgundy fingernail and pulled out the enclosed letter.

"Ah," she said, reading quickly. "This one is about that sexual harassment case of ours, and it's marked 'Highly Confidential' and addressed to that old rat K-S himself." She pushed her typing chair across the floor with an expert kick, to bring her into contact with a very large and highly complex scanner. She lifted the glass cover and put the letter in, then pressed a large red button marked 'Continue?'. The scanner flashed, and an image of the letter appeared on the screen in front of her. She typed the addressee, date, and other key details into the system, then clicked on a button marked "It's all automatic", took the letter from under the glass and threw it into the bin.

"See," she said, "now it's all automatic. James in K-S's office will see that the letter is for K-S, and bring it to his attention. See, it will come up on his screen like this." She pointed a fingernail at a list on the screen headed 'Outstanding!'. There, an entry showed the letter's date and addressee.

I asked what would happen if James missed the entry, or if he was sick that day.

"Oh, Julie in Accounts keeps an eye on it," said Marge. "She's good at that sort of thing. If any letter is Outstanding! for more than a day Julie phones the person and tells them to read it."

I was about to ask what happened when Julie was sick, when Kingsby-Smith himself walked past Reception, and put his head through the mail window into the room. Immediately the two mail ladies started sorting mail, pressing keys, scanning, answering phones and generally making themselves very busy. He looked at me angrily over the top of his bifocals: "Hope you're not keeping these good ladies from their work?"

Accounts

Julie in Accounts was the only completely sane person I met that day. She was able to explain in detail just what happened to a letter after it was scanned.

The mail ladies would code a letter up with the addressee, and then it would appear on the addressee's Outstanding! list. The addressee would then read the letter and decide what to do with it. The options were: delete, file or reply.

If they decided to file the letter they would be asked for a matter number (a bit like a job number, or a customer number), and the letter would disappear into the bowels of the server until it was called up again later for use in a court case. If they decided instead to delete it, the letter would disappear, along with any record that it had been received in the first place (the original having been destroyed in the mail room).

If the letter needed a reply, the lawyer involved would press Ctrl-P on their keyboard ('P' for Pitmans, of course) and dictate directly into a microphone attached to the computer, a reply to the letter that they had on the screen in front of them. The sound of their voice would be recorded by the system and notice of the recording would appear on the Type/Pend list of that lawyer's secretary, who would then audio-type the reply and press Ctrl-C ('C' for carbon copy) to send the typed copy back to the lawyer for checking.

Once happy with the text, the lawyer would print the letter, sign it, and put it in their out-tray, where it would be picked up once a day by the secretary and taken to the mail room for posting.

I asked Julie why someone like her in accounts was keeping an eye on the system, and she pulled an invoice at random from the pile on her desk. I read: "To correspondence, as forto the matter in attendance: $1530 - Correspondence System reference H76HUHU86655". She was interested in the system because is was a major revenue-earner.

The Managing Partner, again

"Well, what do you think of our little system?" beamed Kingsby-Smith across his quarter-acre desk top. "Pretty neat, eh? I can tell you that some of our competitors are still writing letters using word processors! Hah!"

He then proceeded to tell me that the system processed up to fifteen letters a day, and that the partners of the law firm were each given by the System Administrator a 4 cm thick printed report daily showing every single time the system was used - complete with the time of use, which computer, which user, how quickly they typed, a list of the keystrokes, the time of each keystroke, how hard the key was pressed, the room temperature at the time, and so on.

Then he leaned across the desk at me (luckily, it was a broad desk) and said in a conspiratorial tone that the firm was thinking of releasing the Correspondence System onto the market, and already had enquiries from as far away as Adelaide. Law firms in the City of Churches were simply miles behind the times (he told me) and would fall over themselves to buy a spiffing up to date system like theirs.

"And - apart from teaching the new staff how to use it - that's where you could come in," he said. I shuddered.

"I want you to write this manual so that it will make this system sell like hot cakes. Spare no expense: use one of those leather-bound three-ring binders, with plenty of gold leaf on the front. And I want the manual illustrated."

I mumbled something about a picture being worth a thousand words.

"No, no, not that kind of illustrated," he chortled. "Illustrated, like one of those medieval manuscripts. Spare no expense! Hire only the best monks!"

Audience and task analysis

I retired to my office, and poured myself a stiff instant coffee. It was going to be a long night.

The first question on my mind was: what had I forgotten to ask?

Then I had to figure out what the audiences for this documentation were.

And after I'd figured that out, I needed to think about what tasks they had to perform when using it.

Then I had to think about what information they needed in order to perform those tasks.

Then I had to find some monks.