Documentation Standards › Considerations › Standards For Preparing Text Documentation › Using Sub-documents

Using Sub-documents

Break large documents into a number of smaller documents and create a master document to control their printing. This gives you greater flexibility as follows:

• It is quicker to load, edit, and replace a small document.
• The same sub-documents may be assembled in a number of different ways for different purposes.
• It is easier to find text within a small document.

The following points should be observed when writing specifications, program descriptions, and operator instructions.

• Split a complicated series of instructions into a series of numbered ‘cookbook’ steps. For example:

  Not: "Adding a new client and his address is a multi-step process in which first the client is added using the new client display (unless the client was already a supplier, in which case you use the conversion display); and then add the address using the address display, although in the latter case the final step is not necessary."

  But rather: "To add a new client:

  1. Decide if the client is already a supplier.
  2. If the client is not already a supplier:

     – Add the client using the new client display.

     – Add the client’s address using the address display.

  3. If the client is already a supplier:

     – Add the client using the conversion display."

• Use an active voice. For example:

  Not: "To display messages, the user should press F6."

  But rather: "Press F6 to display your messages."

• Write in terms of what the user is trying to achieve. For example:

  Not: "This program performs a database add via a validator subprogram to the customer header and detail files."

  But rather: "This program lets you add new customers to the system".

• Work forwards in time. A simple narrative is usually more straightforward. For example:

  Not: "Before you can do this, you must first add a record, before you add a record you must yourself be enrolled as a user, before which you must decide who has enrollment rights."

  But rather: "To be able to do this you must first decide who has enrollment rights, secondly get him to enroll you, and thirdly, add a record."

• Avoid jargon. It is legitimate to use a small vocabulary of specialist terms that a computer user may reasonably be expected to know, such as workstation, cursor, and command key, but any other terms should be explained.

  Not: "The workstation terminal Help command function key provides WYSIWYG context-sensitive Help text by making a call command request to invoke the interactive on-line Help facility, which has self-extending scroll-through sub file and vectored entry. The Help display program is invoked as an interrupt using a put-override technique so that existing modified input field values are not overlaid by a subsequent put/get."

  But rather: "When you press the HELP key the instructions for the current panel will be displayed. If there is more than one page of instructions, they may be displayed by pressing the ROLL key. Any data that you have already entered will still be there when you return from the Help Text display.

• Place new terms in italics when they are introduced so as to emphasize that they are jargon words: The sub file, a special type of repeating data structure that can be used on displays, is a jolly clever idea."

  Where specialist terms are introduced, use the same term consistently. Elegant variation is not required in computer manuals.

• Be as specific as possible; use concrete terms rather than abstract ones. For example:

  Not: "Various utilities may be used to manipulate text".

  But rather: "Both the Edit source and the Edit text command may be used to create or change Help text".

• Avoid compound phrases; they tend to be very ambiguous. For example:

  Not: "RECORD ERROR"

  But rather: Either, "A error has occurred on processing a record", or "Please log the occurrence of an error in the appropriate place".

• Do not repeat what is already apparent from the context, nor that which could be more efficiently described centrally (such as instructions on how to use a workstation, how to display second level message text).
• Provide examples and instances to illustrate the points you make. Counter-instances may also be useful. For example:

  Not:

  But rather: For example: - "* Not: ........."

• Provide frequent sub-headings and captions to break up the text. Captions enable readers to "hone in" on the information that they are looking for —and to skip that which they are not.
• Ask yourself, ‘What are the questions which would be crossing the mind of someone reading this?’