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:

• Basic literacy, including a respect for conventional spelling, punctuation, and grammar, is a fundamental requirement.
• The layout and organisation of a document should help the reader to understand its structure and find information.
• The text of a document should be physically easy to read.
• A user document should have more readers than writers. It is, therefore, cost-effective for a writer to spend his own time in order to save his readers’ time. It is wrong for a writer to excuse a shoddy or difficult-to-understand document by claiming that it saved him time doing it that way.
• Avoid irritating your readers. (Not an easy task, as no doubt this document shows).

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:

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.