Home > Work > Writing user instructions

Writing user instructions

An area of software development that is often neglected, especially by in-house development teams, is writing end user documentation.  I don’t necessarily mean a vast manual (which will probably never be read) but simple Help screens or an Installation Guide – anything that will be used primarily by somebody outside the immediate development team.

This is a shame, as we often work valiantly to deliver what our customers want, but then find that when we finally release it, the customer can’t work out how to install it or use it properly because the documentation is incorrect, or incomplete.   Shoddy documents also give an unprofessional impression.

It is extremely difficult to do this well, not helped by disincentives to get on with it.

Deferral.  Even when sufficient resources are allowed by the project plan (and given the all too frequent poverty of planning in many projects, this is usually one of the first areas to be cut out), it is a job many of us in IT prefer to postpone, for more interesting tasks. 

Ability.  Many of us are not all that good at writing, hence the choice to study Computer Science or Engineering, rather than English or History.  Up to now I have worked with only one colleague with the skill of being able easily to write clear instructions on how to do something.

Lack of detachment.  Because we are so close to our own work, and we understand it so well, we can’t see the deficiencies in what we write.  The human brain has an amazing capacity to interpret words to mean what we think they say, rather than what is actually written.  This is especially true where we know the subject matter well.

So what can we do to make things easier?

In my recent role I was responsible for making sure the Installation Guide is kept in line with each release.  I’m not looking at style (however see six simple guidelines and more detailed advice on how to write for busy, grouchy people) but how to produce accurate content without making the job an ordeal.

Here are some suggestions based on my experience:

Start early. It is much easier to build documentation up incrementally, rather than to wait until the system is nearly finished.  This also stops it from becoming a massive task in its own right that needs a large chunk of time on the project plan, probably when everybody is already working flat out to meet a tight deadline.  Start with a bare bones outline and fill in the details as they are known, and keep refining. 

Record exactly what we do. Step by step – as we do it, however trivial.  An Army Major on a Defence project I worked on a few years ago referring to the users of his system, called this “Monkey see, Monkey do” – I never decided whether he meant the NCOs or Generals!  Screen prints are useful but not essential (especially if the look and feel is still subject to change).

Lots of pairs of eyes. Just getting someone to review the document for readability and factual accuracy is not enough.  It helps to find someone brand new to run through it unaided and see where they struggle. In my current project our test team verify the installation guide each time they build a new release, and even though they share it around they are still too familiar with it to spot everything.  Next it is followed by the client test team, and lastly the production support team carries out a dry run of a release and so we get a third real time review of content before it is finally used.

By doing all three, we gradually refined the documentation as we went along, and it was pretty accurate by the time we went live.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: