Recent Changes - Search:

add Technology page

hide

Technology


hide

Topics


show

Changed

Visitor's book Site map pmwiki-2.3.32

Doc Template Reqs

A document template can provide numerous benefits, lets look at what it could assist with, and perhaps what it won't.

Requirements

A template assists with two main requirements:

  1. providing an outline structure, eg through the provision of headings, metadata (in properties, headers, footers, and standard structures such as revision histories and approval tables), and perhaps guidance for the content that populates the structure
  2. providing a look and feel, generally through style sheets to facilitate consistent and professional presentation, and allow a document to preserve its layout after maintenance, or changes in page setup.

Note that these two requirements are quite separate, although often confused. It is generally considered imperative to separate content from presentation.

Structure

Lets take the structure first, perhaps because it is less contentious. Structure provides the common features in a standardised way. A template can provide a superset of components from which a user can then pick and choose. Some structural suggestions are:

  • a document should have only one page header and one footer, no matter how many sections. Use the page setup options if the first (eg title) page requires them to be suppressed or different.
  • a document should use the document properties, both for standard properties such as Title, Subject, and Author, and for custom properties such as version number, version status (eg draft, final), and version date.
    • in preference a document should refer to properties, linking properties to bookmarked text is fragile and unmaintainable in practice.
  • The page footer and page header should be driven by metadata, ie through the insert field command.
    • Page header suggestion <company> | <title> | <subject>
    • Page footer suggestion <file name (excluding path)> | Page <page number> of <number pages> | <version number> <version status>
  • Artefacts such as table of contents, table of figures, index, cover page, logos can be set up for ease of use
  • Standard revision histories, approval (or signoff) tables, disclaimers, and copyright statements, etc can be included

Look and Feel

Templates must provide the necessary styles to cater for most and preferably all formatting needs, if not they degrade into a morass of formatting variations. The goal of a template should be to provide the necessary styles to facilitate and ease document development and maintenance. In particular this includes character styles for bold and italic, bulleted, ordered, and continuation styles (to half a dozen levels of indent). Some specific suggestions are:

  • ensure sure the normal (and body text) styles include Keep with next and Keep lines together
  • provide a style (say normal break) which which does not include Keep with next to allow pages to break automatically
  • ensure tables are formatted with table styles. Tables should not have allow row to break across pages set and should be set to Autofit to contents, and then, if desired, preferred width 100%

White space

  • Avoid the use of hard page breaks (except in front of top level headings).
  • Do not use section breaks (unless changing the orientation of the paper or forcing an odd or even page).
  • Balance the use of white space,
    • Suggested margins: 2cm top, bottom, left, and right
    • Suggested gutter: 0cm
  • never use space characters, tabs, or blank lines to force white space
    • use styles to generate white space when required
  • float images if necessary to the right

Styles

Modern word processors are based on styles. This means that they are designed to be most useful and effective when document styles are used consistently and throughout a document, and shared across documents. Styles will reduce maintenance and will improve consistent presentation. You have to understand styles to use them properly

Forms and Automation

In a word, don't.

  • forms have serious shortcomings in saving and printing.
  • automation is just irritating, who wants to set through a series of inane steps

Technology

  • templates must be saved with the template file extension, otherwise they don't work under Windows.
  • templates should be referenced in Templates and Add-ins and should be set to Automatically update document styles
  • templates are living documents, they must have an owner who approves reasonable requests to change and enhance them

Documentation

Templates are not stand alone documentation. You can't expect someone to use a template without describing its usage and features. If you want to have a template document standard you need to document (in a separate document) the standard and template usage as follows:

  • why you should use them and fill them in
  • the use of the structure, including perhaps examples of use
  • the styles supplied, including examples of use

See also

tahi Page last modified on 2011 Jun 14 12:41

Edit - History - Recent Changes - WikiHelp - Search - email page as link -> mailto:?Subject="KiwiWiki: Document Template Requirements"&Body=