Document format

From TechWriter Wiki

Jump to: navigation, search

Contents

Introduction

Document format here refers to the physical format in which the document will be produced. The document format is likely to dictate (or be dictated by) the following factors:

  • The method of reproduction;
  • The binding (if applicable);
  • The method of delivery;
  • The way in which the document will be used;
  • The environment in which the document will be used.

In many cases (and typically for most in-house publications), it is assumed that the document will be produced on plain loose-leaf Letter (or A4) paper, and reproduced in black-and-white. Sadly, this assumption is often looked upon as a cast-in-stone edict, when in reality that need not be the case. It is often worth investigating other formats that may be possible, preferable, or even essential.

This page identifies some of the possible document formats, and lists the advantages and disadvantages of each. The 'document' formats discussed are:

  • Loose-leaf documents;
  • Bound books;
  • Sticky labels;
  • Keyboard templates;
  • Pocket guides or quick reference cards;
  • Microfiche;
  • On-line help.

Loose-leaf manuals

Loose-leaf documents - more often than not stored in ring binders - have become the de facto standard for most types of technical communications. Loose-leaf manuals almost always utilize papers and binders of a 'standard' size (A4, A5, Letter, Statement, etc.). Standard-size binders are usually cheap and plentiful, and readily available from most office stationery supplies. Finally, most offices are already well equipped to handle loose-leaf documents. They have the paper, binders, photocopiers and hole-punches, and few Procurement groups object to the Documentation Department ordering paper and binders!

This makes it a particularly cheap form of document production, although one could argue that it is the popularity that has driven the cost down and not the low cost making them popular. Regardless of the reason for its adoption, there is a very compelling reason for the Technical Communicator continuing to produce documentation in this form: the photocopier.

Most technical documents, and certainly all successful ones, will at some point be photocopied (copyright considerations notwithstanding), and this photocopying will almost certainly be done on a monochrome photocopier which is probably in desperate need of a service (or at least a good cleaning), and is loaded with A4 or Letter sized paper. Given, then, that the final mode of reproduction of the document will be in this format, it may be wise to design the document specifically for this format.

The loose-leaf page also has the advantage that individual pages can easily be added or removed with relative ease (see also "Binding" and "Handling revisions"). Furthermore, because most users are familiar with the concept of ring-binders, they can normally be trusted with the task of replacing old pages with updates!

One additional consideration, however, is the number of rings in the binder, and the corresponding number of holes required in the paper. Three-ring binders are fairly commonplace, but for some inexplicable reason, three-hole punches are not! Even two-ring or four-ring hole punches may not be as prevalent as you think - and not every user may have one on their desk. If a user has to spend time hunting around for a suitable hole-punch, then they may simply not bother, negating the whole point of providing documentation in loose-leaf form. Professional reproduction services (and some in-house copy-rooms) will punch holes in materials for you (several are equipped with 'drill-press' type punches that can be adjusted for any number of holes). Here, you should take care to ensure that the documents are punched with the same number of holes for which your users have binder rings.

When distributing updates to loose-leaf manuals, you should, therefore, pre-punch the updated pages if possible. This will make sure that the pages are punched with the correct number of holes, and the user will appreciate the consideration whether they have the correct hole-punch or not.

Bound books

In contrast to loose-leaf manuals, the advantage of bound books is that the pages are always kept together. There is no danger of information being misplaced or removed. In some circumstances, this is an incredibly strong selling point. Consider the case where the safety information for a piece of machinery absolutely must be kept together with the operating instructions for the machinery. By binding them together, you can guarantee that the operator has the safety information to hand as they read the operating instructions.

However, this strength can also be a weakness. Because all of the pages are permanently bound together, it is impossible to replace individual pages. Any update necessitates re-issuing the entire volume. This is fine if the likelihood is that all pages will require updating at the same time (for example, an operations manual for a specific version of a product, which will be replaced with every new version), but is unsuitable where some, but not all, of the information is subject to (relatively) frequent change.

The final advantage of bound books (and especially hardback books) is that they tend to be sturdy (or at least sturdier than loose-leaf binders). This makes them useful for documents that will be referred to often, or documents that may be subject to rough handling (for example, being carried from home to college and back every day). Because bound books are sturdy they tend to last longer, and are therefore useful for long-term reference material (the hard-bound Encyclopedia Britannica is a good example of this type of use).

Wall-charts

Traditionally, wall-charts have been used to display large, complex diagrams that are simply too detailed to fit on a smaller sheet of paper. Good examples of this type of wall-chart are floor plans, and wiring or piping diagrams. Although these are excellent candidates for wall-charts, they are not the only candidates. Wall-charts are equally as useful in the following situations:

  • Where the information must always be visible (such as safety information);
  • Where the information is referred to on a very regular basis (such as telephone lists);
  • Where it may not be physically possible to open a book and flip to the correct page (such as in an operating theater);

Bear in mind that wall-charts do not necessarily have to be huge wall-coverings. A single-sheet document designed to be pinned to a cubicle wall is very simple to produce, and can be a very effective communication.

Similarly, wall-charts do not have to be detailed. Consider the case where a warehouse operator receives loading instructions in net weights, but all product is bagged and palletized. A large poster tabulating net weights to numbers of pallets and bags, in 12-in (30cm) high lettering, would be an extremely effective communication, as the warehouse operator would be able to read it from their forklift.

The main problem with wall-charts is that they are not that easy to produce. Few organizations have flat-bed plotters available for everyday use, and so reproduction may have to be contracted out. This will then obviously raise the price of the publication. It is also worth checking that the user will have the wall-space available as many offices are open-plan, or have wall-to-wall windows. (See also "Working Environment", under "Defining the Audience".)

Sticky Labels

The main advantage of sticky labels is that it is possible to place the information (the 'document') at exactly the point at which it is needed, and the information is instantly visible. The user does not have to search for the information, or go somewhere else to retrieve it; the user does not need to flip a page, call up a help file, or anything else - the information is simply there. Furthermore, the use of sticky labels ensures that the information is always kept with the device to which it relates - which makes them especially useful for safety information.

The disadvantage is that it is not normally possible to put much information on the sticky label. Naturally, this depends on the size of the sticky label, but labels are only really useful for two or three short lines of text. Furthermore, there may not actually be a suitable clean, flat surface of the required size onto which the label could be stuck. Finally, the fact that the label is (hopefully) permanently stuck to the relevant device may also prove to be a disadvantage in that changing the information may prove difficult, as it necessitates either removing the old sticker (where possible) or placing a new sticker over the top (which is only practicable a small number of times...).

The obvious use is for placing the telephone number of Technical Support on a user's workstation. Another good use is putting information on how to load letterhead paper into a printer directly onto the printer itself, or sticking common menu options onto the back of a hand-held device.

Keyboard templates

Useful for software applications, especially those relying on the Function keys across the top of a standard 102-key keyboard (as was the case with SAP R/2).

An example of a keyboard template for a standard 102-key keyboard is shown below. The black rectangles are holes that fit over the top row of keys (Esc, F1-F4, F5-F8, F9-F12).

Pocket guides

A pocket guide is a worthwhile consideration where the user of the document may be away from their usual workplace at the time that they need the information. Examples would be warehouse staff taking inventory on handheld computers as they tour the warehouse, or sales staff out on the road visiting customers.

Most `pocket' guides are not really designed to fit into a pocket. Some are far too large to fit into even the most voluminous of pockets - as evidenced by the Pocket Oxford English Dictionary! Additionally, you cannot normally guarantee that the user actually has pockets - women's dresses seldom have suitable pockets, men's shirts don't always have pockets, and people's back pockets are usually already filled with an overstuffed wallet. The term `pocket guide' is therefore better interpreted as "more portable than a standard book".

Given this, consider the places and circumstances in which the pocket guide will be used, and the way in which it will be transported to and from these places.

Quick reference cards

Quick reference cards differ from pocket guides in that they are generally not designed to be `portable', often being referred to at the user's primary workplace.

Microfiche

(TBD)

On-line help

(TBD)

Personal tools
Support