Starlink Project
Starlink General Paper 28.8

M D Lawden
A C Charles

25 September 1997

How to write good documents for Starlink


This document gives advice on how to write good Starlink documents. It lists Starlink documents which users said they liked in the 1994 Starlink Software Survey, and identifies common characteristics of style and organisation which can be recommended to authors.

Various features of documentation which the authors believe to be harmful are specified, including common problems with pages produced for the World Wide Web. Many of these will inevitably reflect the taste of the authors, and these may not correspond to your own. However, they derive from our belief that it is right for an author to spend time and effort on a document in order to save the reader time and effort in reading it.


1 Introduction
2 Starlink Software Survey
 2.1 Best documents
3 Planned improvements to Starlink documents
 3.1 Cookbooks
 3.2 Hypertext
4 World Wide Web
5 Good style and organisation
6 Document diseases
 6.1 Web diseases
7 References
A Standard elements of a Starlink document
 A.1 Code, date, filename
 A.2 Standard headers, type size, page size, layout
 A.3 Title
B Producing a document
 B.1 Starting or revising a document
 B.2 Using LATEX
 B.3 Using Star2HTML
 B.4 Submitting a document for distribution