Styles and standards

From TechWriter Wiki

Jump to: navigation, search

Contents

Key considerations

  • Follow any existing in-house style
  • Define a house style if none exists
  • Match existing document styles
  • Adhere to relevant industry standards
  • Readability - consider tools for measuring this

Following an existing in-house style

If an in-house style already exists (either for the project, product or organization), then obtain a copy of this, and ensure that the new documentation follows this style. However, do not feel that you must blindly follow an existing style where it is inappropriate for the type of document being produced (but bear in mind that deviation from the norm may require high-level justification!).

Defining an in-house style

If no in-house style exists, consider developing one yourself. However, try to plan ahead - any self-penned standard must be followed (both by yourself and others) for future publications.

You may find it easier to look for other 'external' styles or guidelines, and adopt these instead of defining an in-house style from scratch.

Once an in-house style has been defined (or an external one adopted), make sure that this is made available to everyone who needs it.

Matching existing document styles

When changing an existing document, try to match the existing style as closely as possible (even if it isn't the style you would personally choose). The alternative is re-writing the entire document (and possibly others in the same series) to meet your preferred style; this is seldom justifiable.

Study the documentation (or several across the set, if applicable) before starting work.

Don't change the existing document out of personal preference - it may turn into a much bigger job than you anticipated.

External standards

Standards organizations

  • ISO - International Standards Organisation
  • BSI - British Standards Institute
  • IEC - International Electrotechnical Commission
  • ATA - Air Transport Association of America
  • IEEE - Institute of Electrical and Electronic Engineers

Useful British standards

  • BS4884 Specification for Technical Manuals:
Part 1 - Specifications for preparation of essential information
Part 2 - Guide to Content
Part 3 - Guide to Presentation
  • BS4899 Technical Manuals
Part 1 - Guide to user's requirements for technical manuals
Part 2 - Best practices for presenting information in technical manuals
  • BS7649 Guide to the design and preparation of documentation for users of application software

Other useful standards

  • AQAP 11 - NATO Guideline for the Specification of Technical Publications
Uses the same categories of information as BS4884, but goes into more detail about the exact information to be found in each category. Superseded by AC/301 in February 1993.
  • ATA100 International Specification for the Production of Commercial Aircraft Technical Publications
  • AvP70 Air Vehicle Publications NATO Specification for Military Aircraft Technical Publications
  • AECMA 1000D Specification of the Production of Commercial or Military Maintenance Publications
  • AECMA SE Simplified English

Producing a standards document

  • Should be done by widely-experienced writer and illustrator
  • Avoid rigidity - try to provide a guide, but make it a clear one
  • Give examples
  • Draft the standard and have it tested
  • Ensure standards are best for the user's requirements (do not standardize just for the sake of it).

Producing a style guide

This is likely to be more informal than a standards document, and is generally produced in-house, to give some guidance to the authors doing the work, to ensure that all documentation has a 'common' feel.

Things to specify:

  • Page size, margins and layout (indentation of text blocks, etc.);
  • Text - font style and size;
  • Headings - Hierarchy of headings (usually indicated via font size, bold/italic/underline, and indentation)
  • Highlighting of specific information (positioning/labeling of warnings or notes). Possibly cover the inclusion of specific information (though this is veering into Standards territory)
  • Writing style, choice of words (possibly simply refer to another style guide, such as the MLA style guide).

Recommended books

    

Personal tools
Support