TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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>).
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,
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
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
'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
'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
'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
'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
'(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>