A demand for better documentation was a marked feature of the Starlink Software Survey of 1994. This is shown by the answers given to questions 3 and 4.
Question 3: How could Starlink software be improved?
Out of 18 possible answers, the 2nd and 3rd most popular (totalling 17% of the vote) were:
Question 4: How could Starlink Documentation be improved?
Out of 23 possible answers, the top four (getting 45% of the vote) were:
The message is loud and clear: users want more help with how to use the facilities provided by a piece of software, rather than just plain descriptions of the facilities provided.
The survey also asked users to mark the quality of the documents provided with each software item they used. The ones which got the highest average marks (starting with the best) were:
These are the documents the users said they liked best, so take a look at them and consider modelling your documents on their organisation and style. In section 5 we list what we think are common characteristics of these documents. These characteristics can be used as guides for your own writing.