Re: Style Sheets - long post

[Margaret Gerard <margaret -at- TOSHIBA -dot- TIC -dot- OZ -dot- AU>]

Linda,

We would be lost without the control of documentation standards which is
 possible through the use of FrameMaker templates.  FM is the only
 wordprocessing software in use here and the rule is that every document must be
 written using a template.  (Personal stuff excepted.)

We have a template for every type of document produced here i.e. Procedure,
 Requirements Specification, User Interface Definition, Project Plan, Project
 Proposal, Subsystem Overview, Detailed Design Description, Test Plan, Test
 Procedure, Report, User Manual, Memo, Letter, Internal Fax, External Fax, Visa
 Application and a whole bunch of forms.  The first eleven are directories which
 contain the template files requred to produce that document i.e. Title, TOC,
 LOT, LOF, Body, Appendix, XREF, IX.  These are collected in a book file.  The
 last five are single files which are pretty straightforward.  One nice thing is
 that in the fax template we have set up a variable (called e.g. XYZ Section
 Mgr) for each of the frequently faxed addressees, containing the name,
 organisation and faxno separated by tabs - this is a real time saver because
 when we get a whole swag of changed names and/or faxnos (happens about twice a
 year in Japanese companies) we need only change the template.

The template files are accessed via the NEW button on the Frame main menu or
 more usually, by using a shell to copy the document template directory to the
 work area (under configuration control).  In this way, you get the book file in
 a usable form.

Setting the templates up was a slowish process as input was required from all
 managers and team leaders but the consensus approach has meant better
 acceptance of the standards.

The templates embody all the appearance standards you would expect but also
 state what the content of the document must include; also there are
 instructions on things like cross-referencing and how to include case tool
 diagrams.

In addition to the templates, we have a procedure document called "Documentation
 Standards and Procedures" which explains the process of using the templates and
 is the arbiter of things like punctuation.  The TOC of this document is listed
 below:

TITLE
DOCUMENT REVISION HISTORY
TABLE OF CONTENTS
LIST OF FIGURES
LIST OF TABLES
1.      INTRODUCTION
2.      SCOPE AND FIELD OF APPLICATION
2.1     Scope
2.2     Field of Application
3.      REFERENCES
4.      DEFINITIONS
5.      ESTABLISHING THE DOCUMENTATION REQUIREMENT
5.1     Document Identifier Format
        5.1.1   Identifier Components
        5.1.2   PPPPPPPP
        5.1.3   CCC
        5.1.4   NNNN
        5.1.5   TTT
        5.1.6   R#.A#
        5.1.7   Document ID Categories and Type Codes
6.      PREPARING THE DRAFT
6.1     FrameMaker Templates
        6.1.1   Benefits of Template Usage
        6.1.2   How to use a template
        6.1.3   Template files
6.2     Other FrameMaker Features
        6.2.1   Understanding the Paragraph Formats and Catalog
        6.2.2   Understanding the Character Formats and Catalog
        6.2.3   Using the Tables Feature
        6.2.4   Using the Cross Reference Feature
        6.2.5   Using the Spelling Checker
        6.2.6   Using Change Bars
6.3     Writing Style
        6.3.1   Sentence Structure
        6.3.2   Paragraph Structure
        6.3.3   Lists
        6.3.4   Punctuation
        6.3.5   Abbreviations
        6.3.6   Capitalisation
        6.3.7   Spaces
        6.3.8   Emphasis
        6.3.9   Numbers and Measurements
        6.3.10  Quotations
        6.3.11  Rendering Keying Sequences
        6.3.12  Incorporating Figures in Text
7.      REVIEW, APPROVAL AND AUTHORISATION
7.1     Review
7.2     Approval
7.3     Authorisation
8.      DISTRIBUTION
8.1     File (electronic) copy
8.2     Hard copy
9.      MAINTENANCE
APPENDIX A - TEMPLATE DIRECTORIES
APPENDIX B - PARAGRAPH TYPES
APPENDIX C - DOCUMENT VARIABLES
APPENDIX D - PARAGRAPH TAG EXAMPLES
APPENDIX E - AUTONUMBER FORMATS
APPENDIX F - CROSS REFERENCE FORMATS

This document has not proved to be a sinkhole of man hours - it has not yet
 required revision.  It was very thoroughly researched while in draft and its
 focus is what writers need to know that cannot, for various reasons, be
 answered by referring to:  the appropriate template, FrameMaker documentation
 or references such as the Aust. Govt. Style Manual, Fowler's Modern English
 Usage or Chigao Manual of Style etc.


While I agree with much of what Chuck Banks had to say on this subject, I know
 that our group could not be as productive without our current set-up.  At the
 very least, it saves review time because many things that people would
 otherwise want to chew over are unarguable.  Documents are reviewed once (at
 the end of the review process) for conformance to the standards leaving other
 reviews free to concentrate on technical issues.

Hope this helps you clarify your situation :>)

Regards,
Margaret Gerard          email: margaret -at- toshiba -dot- tic -dot- oz -dot- au     fax: 61 2 4187791
Toshiba International Corporation
Sydney
Australia