How Not to Write Software User Documentation

There are few things that make my heart sink more than software user documentation that is just a description of the software's menu items and dialog boxes.  When I go to user documention, I do not go to it in order to find out whether the File menu has an Open option, nor whether I can use the latter to select a the file I want to open.  This sort of thing is obvious to almost everyone nowadays, and where it is not obvious it can be found by looking up and down the menus and at the dialog boxes themselves.

If you are a writer of software user documentation and you ever find yourself tempted to write user documentation like this, then I recommend that you first read the following words of advice taken from 'Read Me First, A Style Guide for the Computer Industry' (2nd Edition, published by Sun Microsystems Inc, 2003):

As a writer, you research, organize, and communicate information for the reader, who depends on you. In your relationship with the reader, you are the expert. Keep this point in mind when you make decisions about what information to present and how that information addresses the reader's questions.

Often a product provides several different ways to accomplish a single task. You might decide that you owe the reader an explanation of each method. However, remember that the reader is more interested in using the product than in understanding all options. Choose the best method for most of your audience, and tell the reader to use that method.
After you commit to the best course of action, you might explain to the reader that other methods exist. Tell the reader where to find your descriptions of those methods. Also tell the reader why and in what situations options A, B and C are useful.

(You will also be doing your readers a service if you tell them clearly when something is difficult, or impossible to do, rather than remaining silent and leaving them to find out for themselves.)

One of the most important contributions a writer makes is to anticipate the reader's questions and provide appropriate answers. A writer must anticipate questions about related topics as well and provide cross-references to where those questions are answered. As the subject matter expert, a writer can create a climate of understanding that is far more significant than merely recounting facts about the product.

See that?  The job of a writer of software user documentation is to "create a climate of understanding", not just to recount a list of facts about the product!

Day Three as a Teaching Assistant

Not so much to report for my third day.  I must be getting used to it.  I did spend a couple of lessons sitting next to some boys who had reputations for disrupting classes.  I talked with them about the work and how boring it must be to them, and various other things.  The first one settled down and worked quite well.  The other was worried that his friends might be laughing at him (I couldn't see that they were) and only did a little work, but at least he wasn't too disruptive.  The rest of the lessons were less memorable for me, at least.

Well, the first three days haven't put me off my plan of becoming a teacher.  We shall see what happens next week.

Day Two as a Teaching Assistant

A less stressful day than yesterday.  Mostly spent with older children: years 10 and 11. 

The first lesson was IT but the children had been allowed to finish off work from other subjects, and most of them had completed this.  I noticed that some of the boys were surreptitiously playing an online mountain bike game.  One of the girls had a rather unusual first name so I suggested that she look it up on Google and she found a town near New York with the same name.  This seemed to please her very much.

In a later lesson, a group of quite troublesome girls were reduced to complete silence by being shown a video about healthy eating and weight loss.  The teaching assistants didn't have much to do in that lesson. 

Then there was another rather chaotic chemistry lesson, but this one had at least four disruptive boys in it which made things very difficult for the teacher.  It was a practical lesson involving adding hydrochloric acid to fragments of limestone.  I noticed that one table of children had been missed out in the handing out of equipment, and they hadn't complained, nor did they even seem to care, so I gathered up a set of equipment and took it over to them and got each of them doing it.  They seemed to enjoy it but I don't know whether they will remember anything of worth from it. It must be very difficult for children to distinguish what is relevant in an environment like that.  The teacher must seem to be more concerned with keeping the children on their stools, stopping them talking, getting them to write down predictions, and preventing them spraying each other with acid.  For the children, the intended message (the actual chemistry) must be completely swamped by all this extraneous noise.

The last lesson was a complete contrast:  a bright attentive class with an enthusiastic, knowledgable teacher.  I hadn't realized that the history of medicine was an option in the history syllabus, but it does seem to have been an inspired choice to include it.  The lesson was fascinating and took me back to my grammar school days.  Several times I had to stop myself from putting my hand up to answer the teacher's questions myself.  When I become a teacher, I want my lessons to be like that.

A good day.  I caught a bus back into town and only walked the last mile home.  I don't feel so tired tonight.

Day One as a Teaching Assistant

Yesterday was my first day back at school in 22 years.  I shadowed various other teaching assistants as they went about their work.  I saw 4 very different lessons, all involving at least one child that had been identified as needing extra help (providing that help is what teaching assistants are for).  It was all rather confusing for me: going into a class in which the children were continuing some work which had been explained to them in a previous lesson, and me trying to pick up what was going on and what the teacher was trying to achieve.  However, when I get into the job properly this confusion should disappear. 

I started with an art lesson in which the children were assessing each other's work, using checklists that looked as if they had been photocopied from the National Curriculum literature.  It reminded me very much of 'going through the motions' on various software development methods from the 1990's  (CMM in particular).  Then there was a maths lesson on number place value (hundreds, tens and units).  One of the boys several times misread 'four' as 'five' and 'eleven' as 'seven.  I wondered if he wasn't seeing clearly.  He was already wearing quite thick spectacles.  However, he still managed to complete the worksheet and seemed very pleased to have got a complete column of ticks.  Then there was a reading lesson in which the teacher had the children taking turns to read sentences from a rather surreal story about a woman who ran a boarding house but had a laboratory in the basement in which she did experiments in paint technology.  (Yes, this does rather seem like desperate attempt to break stereotypes and promote science both at the same time.)

In the afternoon I was in a chemistry lesson (reactivity series) with older children.  I was impressed with how the teacher coped with difficult circumstances, the room was cold, rather dark, and some of the girls were rather restive.  He seemed to keep control of the simmering chaos in quite an impressive way, and I quite enjoyed this lesson.

At the end of the day I walked all the way home which took me 55 minutes.  Later that evening I suddenly felt very tired and went to bed early.

Darwin's Strange Inversion of Reasoning

The great inversion of Darwin, what McKenzie calls his strange inversion of reasoning, was when Darwin realized that you have a bottom-up theory of creativity, that all the wonderful design that we see in the biosphere could be the products, direct or indirect of a mindless, purposeless process, and this simply inverts an idea that I think is as old as our species, maybe older in a certain sense, and that is what you might call the top-down theory of creativity: it takes a big fancy thing to make a less fancy thing. Potters make pots. You never see a pot making a potter. You never see a horseshoe making a blacksmith. It is always big fancy, wise, wonderful things making lesser things. And so, here we are, we are pretty wonderful: we must be made by something more wonderful still and it's got to be like us, it's got to be the intelligent artificer. It's very scarey for people to give that up, and to begin to think about how our importance doesn't depend on the importance of something still more important. That is, not of that sort. I mean on the one hand I think that a good bumper-sticker recipe for happiness is find something more important than yourself to think about and worry about. There are many such things that we can find to replace the one big important thing which many people think they have, which is God.

Daniel Dennet in this interview by Susan Blackmore  (via The Guardian).