Re: Style Guides and Documentation Standards

["Daniel G. Dresner" <Daniel -dot- Dresner -at- NCC -dot- CO -dot- UK>]

From:  Tom Johnson
> I've been through the process of trying to find out what standard
> even talks about documentation . . .

Are you aware of: BS 7649 1993 Guide to the design and preparation of
documentation for users of application software Price GBP50.00 to
subscribing members of BSI, GBP100.00 to non-members 108
page(s) Committee IST/15 and BS 7830 1996 Guide to the design and preparation of on-screen
documentation for users of application software Price GBP50.00 to
subscribing members of BSI, GBP100.00 to non-members 114
page(s) Committee IST/15?

I am part of a team that is combining them into a single
international standard.

The 'Scope' section of BS 7649:1993 'Guide to the design and
preparation of documentation for users of application software'
reads:

This British Standard gives guidance on the design and preparation
of user documentation for application software.

Application software is software designed to help users perform
particular tasks or to handle particular types of problem as distinct
from software that controls the computer system itself. For the
purposes of this British Standard, application software includes:

- consumer software packages, that is, software products designed
and sold to carry out identified functions, where the software and
its associated documentation are packaged for sale as a unit;

- software for office applications such as word processing,
spreadsheets, databases and electronic mail;
- business software, for example, software for recording and
monitoring business activities such as stock control and
processing orders;
- specialist software for use by professionals, such as accounting
systems, graphic design systems and engineering design systems.

For the purposes of this British Standard, application software does
not include:

- software engineering products for use by computer professionals;
- software for programmable electronic or mechanical systems;
- medical systems and manufacturing systems that require special
safety-related documentation.

This British Standard gives guidance of two types and is structured
to reflect this.

a) Guidance on process is given in sections 2 to 8.

Section 2 gives an overview of the design and development process.

Sections 3 to 8 cover the separate stages and can be referred to
when the stages are being carried out. There are checklists in
annex B which can be used to cheek and record progress.

b) Guidance on detailed design is given in sections 9 to 14.
Sections 9 to 13 cover the content, structure, style, technique and
presentation of documents. Section 14 covers contents lists and
indexes.

During each stage, the detailed design sections can be used as
reference material.

This British Standard takes account of the fact that some of the
documentation will be provided by the software itself, possibly as
on-screen displays. It describes how to establish what information
users need, how to decide which information should be provided on
paper, and how to prepare documentation containing that
information. It does not cover the design and preparation of the
software's screen displays, nor of other on-line documentation.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
and the scope of BS 7830:1996 'Guide to the design and
preparation of on-screen documentation for users of application
software' reads:

1.1.1 General

This British Standard gives recommendations for and guidance on
the development of on-screen user documentation for application
software. Such documentation supplements the software's user
interface.

This British Standard covers the process of developing the
documentation and gives guidelines for the content, navigation,
style and presentation of the information.

1.1.2 On-screen documentation

On-screen documentation in the context of this British Standard
includes any information users can access on a screen about the
software they are using. It includes, for example:

-context-sensitive displays of names of user interface objects (such
as bubble help or balloon help);
-help status lines that explain what the current context is, or what
the selected object can do;
-context-sensitive displays of instructions and descriptions;
-sets of related topics that users can browse through;
-free-standing documentation systems.


The guidance in this British Standard may be helpful for developing
the following types of documentation, although it does not cover all
aspects of them:

-free-standing documentation systems where there is no related
application software;
-multi-media systems using, for example, video and sound;
-on-screen tutorials and computer-based training (CBT) packages.

On-screen documentation is fundamentally different from paper
documentation in that it is not suitable for reading sequentially,
page by page. In most cases, on-screen documentation consist of
a series of self-contained texts that are relevant to specific
situations within the application. The task of creating on-screen
documentation is to identify these situations and to create brief,
relevant, accurate texts.

1.1.3 Application software

Application software is software designed to help users perform
particular tasks or handle particular types of problem, as distinct
from software that controls the computer itself.

For the purposes of this British Standard, application software
includes the types listed below:

-consumer software packages, that is, software products designed
and sold to carry out identified tasks, where the software and its
associated documentation are packaged for sale as a unit;
-software for office applications such as word processors,
spreadsheets, databases and electronic mail;
-business software, for example, software for recording and
monitoring business activities such as stock control and order
processing;
-specialist software for use by professionals, such as accounting
systems, graphic design systems and engineering design systems.

The guidance may also be helpful for developing on-screen
documentation for the following, although it does not cover all the
issues relating to them:

-software engineering products for use by computer professionals;
-software for programmable electronic or mechanical systems;

-medical systems and manufacturing systems that require special
safety-related documentation.

1.1.4 Overview

There is an overview of the contents of this British Standard,
explaining its structure, in section 2. Annex D explains how
different types of reader can use this standard; it gives simple route-
maps for the different types of reader to follow.

1.1.5 Process

Process recommendations are in sections 3 to 7. They cover the
separate phases of developing on-screen documentation.

Annex A gives checklists for recording and monitoring progress
through the development phases.
Annex B gives checklists that can be used as the basis for
documentation reviews.
Annex C covers evaluation of on-screen documentation systems.

1.1.6 Guidelines for on-screen documentation

Guidelines on the contents, navigation, style and presentation of on-
screen documentation are in sections 8 to 11. Readers should refer
to
these guidelines sections during each phase of the process.

1.1.7 Reference information

Annex E contains lists of books that might be useful to readers.


************************************************************
Danny Dresner
Head of Standards
The National Computing Centre Ltd.
Oxford House, Oxford Road
Manchester M1 7ED, UK
daniel -dot- dresner -at- ncc -dot- co -dot- uk
Tel: +44 (0)161 228 6333
Direct Line: +44 (0)161 242 2352
Fax: +44 (0)161 242 2171
Please visit us at the IT Zone - http://www.ncc.co.uk/
ISO 9001/TickIT Certificate: 928858A

"If it's easy . . . you're not doing it right."

DISCLAIMER: This e-mail contains proprietary information, some or all of
which may be legally privileged. It is for the intended recipient only. If
an addressing or transmission error has misdirected this e-mail, please
notify the author by replying to this e-mail. If you are not the intended
recipient you may not use, disclose, distribute, copy, print or rely on
this e-mail.


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