1 Introduction

This note gives advice on how to prepare good documents for Starlink. It applies particularly to Starlink User Notes (SUN), Starlink Cookbooks (SC), and Starlink Guides (SG), as these are Starlink’s main ways of telling its users how to use its software. Some extra advice is given for World Wide Web pages.

Any judgement about what constitues a good document is bound to be partly a question of taste, and our taste may differ from yours. Naturally, this document reflects our taste. However, a lot of our advice is based on our analysis of the common characteristics of documents which have been judged good by Starlink users.

We believe the following general principles apply to good documents:

The Starlink Document Librarian (Mike Lawden) is responsible for ensuring that Starlink documents reach an acceptable standard. If Starlink published poor quality documents it could suffer political damage which, in turn, could damage our service to users. Because of this, the Librarian has the power to refuse to accept poor documents for distribution within Starlink because of the bad impression they would give of the Project. Alternatively, he may modify them in order to make them acceptable.

Three recent developments have influenced our views on what constitutes a good Starlink document:

Starlink Software Survey, 1994
– this provided valuable feedback from users about what sort of documents they wanted, and what they thought of current documents. (see SGP/43)
Starlink Software Strategy
– this is a response by Starlink to the wishes expressed by its users in the Starlink Software Survey. Among other things, it contains plans for improving Starlink documents. (see SGP/42)
World Wide Web
– this is an important technique for publishing information which makes it easier and faster to use, update, and distribute.

The impact of these developments on Starlink’s document production is discussed in the next three sections. This is followed by a section containing advice on how to achieve good style and organisation in your documents, and a section describing practices which we think are bad and should be avoided. Various technical matters concerning Starlink documents and how to produce them are contained in two appendices.