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:
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.