BS 7830

[Bruce Conway <bconway -at- ISLAND -dot- NET>]

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:
http://www.istc.org.uk/bs7830.htm



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
BSI
committee, and using input from a wide variety of sources, notably a
large
number of ISTC members.

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

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

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
topic.

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
              enough).'

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=