5 Good style and organisation

In Section 2.1 we listed the Starlink documents which the users voted the best available. Do these have any common features which can be used as guides for ones own writing? We took a close look at them, and all or most of them have the following characteristics:

• Well organised and formatted, so the structure of the document is clear and it is easy to find things.
• An abstract or description on the front page, summarising what the document is about.
• A contents list (at the front).
• An introduction and overview.
• A summary of the types of functions provided, and a classified list of commands or routines (by function; not just alphabetical).
• Clear instructions on how to start up the package or use the routines.
• Plenty of examples.
• Detailed descriptions of commands or routines, placed in a separate section or appendix.
• Descriptions of new features or changes introduced by the latest version of the software, and possibly a description of limitations or restrictions.

Any non-trivial document describing a software package or routine library should have this sort of sectioning. Some (such as SUN/1 which surveys the whole of Starlink software) can also benefit from having an index (much easier to produce with the new version of LATEX).

We also recommend the following further characteristics for your Starlink user documents:

• Organise your paper into sections using sectioning commands (see SC/9, Section2).
• Use the list facilities to highlight options or features (see SC/9, Section 4).
• Indent example commands and show them as they appear to the user, including any prompt symbol. Leave a space between the prompt symbol and the command – ‘what you read is what you see’. Thus:
        ICL> CAR_HELP SEARCH

  is clearer than

    ICL>CAR_HELP SEARCH
• Try to keep your formatting techniques as simple and obvious as possible. We find the basic techniques shown in SC/9 to be adequate for all normal purposes.
• Documents are often revised, merged, or restructured many times, so you should make it as easy as possible for this to be done on a computer. In your source document we recommend that you start each sentence on a new line; this makes future identification, insertion, selection, and movement of text very easy.

Starlink is trying to achieve a common style in all its documents, particularly in their format, so as to present a professional and uniform image. To achieve this, we request that you include in your documents the standard elements specified in appendix A.