BS 7830

Subject: BS 7830
From: Bruce Conway <bconway -at- ISLAND -dot- NET>
Date: Tue, 22 Dec 1998 12:56:49 +0000

Just a cut and paste from a Web Page talking about BS 7830. (It was
suggested I look into this after my hypothetical interview question:
"How do you go about handling large documentation projects?", or "How
would you go about preparing this manual for us." So, now you can tell
the prospective employer, "Well, that's easy, I use BS. Number 7830."
(Forgive my humour. No, I haven't been into the Christmas cheer <yet>).

Here's the link it's from:

BS 7830 ? A Guide to the Design and Preparation of On-screen
Documentation for Users of Application Software was published by BSI in
May 1996. It was prepared by a team from ICL under the direction of a
committee, and using input from a wide variety of sources, notably a
number of ISTC members.

People are now using it for active projects for a variety of different
and are finding different parts of the guidance useful. Although BS 7830
not solve all your problems, it is helping people plan documentation
and design their on-screen documentation.

This article explains briefly what BS 7830 contains, shows some examples
how people are using it, and gives some background to why and how it was

What the guide contains

BS 7830 is a guide, which means that it contains advice and guidance,
not rigid
requirements to conform to. It gives you processes to follow to work out
what documentation you are going to provide for
your users and then to prepare it. It also gives guidelines for the
content, navigation, style and presentation of the
documentation itself.

If you have used BS 7649, then the scope and structure of BS 7830 will
be familiar to you. The new guide advises you to
work out who needs to know what, when and how, before you start working
out what it will look like!

The BSI committee was very keen that the new guide should be suitable
for documentation on any type of system,
including minimal display systems such as tills in shops, as well as the
more familiar sorts of computers. Therefore, the
guide is independent of any hardware or operating system. It also covers
all types of on-screen documentation, not just the
big help files that you can navigate through, jumping from topic to

Whatever the nature of your on-screen documentation, the Guide helps you
ensure that your users can find whatever type
of information they want at any time.

How the guide is being used

To get a range of views, I asked a few colleagues who have used BS 7830
for live projects how useful they found it. Here
is what they say.

Person 1 used the guide for designing a very large, free-standing
hypertext system.

'The most useful sections of BS 7830 are the process
sections, particularly because writing on-screen
documentation has elements of writing software (such as
specification and testing). The parts of the text
that are common to paper documentation and on-screen
documentation, such as task and user analysis,
are not really new to experienced authors such as those in
the ISTC!

'Annex D, which explains that not all of the guide applies
to everybody, is important. For example, I'm
not too interested in resourcing and project planning
(don?t tell anybody).'

Person 2 was designing all the documentation for users of a new type of
application development system running under
Windows 95.

'BS 7830 gives you good advice for working out what you
should put in context-sensitive bubble help
and help status lines, and it makes the difference between
?function descriptions? and ?instructions for
tasks? very clear. There is some useful advice in Figures
16 and 50 that stops you putting sets of
instructions in pop-ups, which disappear as soon as you
start to follow the instructions!

'I wasn?t prepared for the amount of testing that would be
needed, although BS 7830 did warn me. I
should have documented my design in more detail, so that
fixing bugs would have been easier. Again,
BS 7830 does advise you to do it, but not strongly enough
(or at least, I didn?t take it seriously

Person 3 was designing the user interface for the help system for a
Windows application.

'The advice in BS 7830 about presentation, use of icons
and signposts, and use of colours is very useful,
because you can show it to the developers to reinforce the
advice you are giving them.

'In fact, the whole guide is useful to show to the
developers, to prove to them that there is something to
know, so they should listen to you. (The developers wanted
an 'exciting' look, with lots of whizzy pictures
and colours. I think it would have driven the hassled
users bonkers.)'

'(Anything make you think I had problems with the
developers on this project?)'
Bruce Conway *** Technical Writer
Member: STC and VIATeC (Vancouver Island)
Tel: 250-336-8338 ( til Jan 1,99)
Tel: 250-474-9939 (after Jan 1,99)
Email: <bconway -at- island -dot- net>

From ??? -at- ??? Sun Jan 00 00:00:00 0000=

Previous by Author: Re: No one reads the manuals
Next by Author: Microsoft & Tech Writers
Previous by Thread: Re: No one reads the manuals
Next by Thread: BS 7830

What this post helpful? Share it with friends and colleagues:

Sponsored Ads