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
- 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
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:
is clearer than
- 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.