2 Starlink Software Survey

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.

Out of 18 possible answers, the 2nd and 3rd most popular (totalling 17% of the vote) were:

• Better on-line documentation.
• Better printed documentation.

Out of 23 possible answers, the top four (getting 45% of the vote) were:

• Cookbooks for specific types of work.
• A more tutorial style.
• More practical examples.
• Better examples for programmers.

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.

2.1 Best documents

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:

• SUN/40: CHR – Character handling routines.
• SUN/39: PRIMDAT – Processing of primitive numerical data.
• SUN/100: TPOINT – Telescope pointing analysis system.
• SUN/33: NDF – Accessing extensible n-D data.
• SUN/105: STARLSE – Starlink extensions to language sensitive editor.
• SUN/110: SST – A simple software tools package.
• SUN/31: REF – Handling references to HDS objects.
• SUN/87: JPL – Solar system ephemeris.
• SUN/90: SNX – Starlink extensions to NCAR graphics utilities.

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.