The link: https://dl.acm.org/doi/abs/10.1145/800060.801172
The full paper can be downloaded as a PDF or viewed online from the link above.
A partial summary of the paper:
- How can documentation be "user-friendly" to many different types of users: from very sophisticated programmers to brand new computer users?
- How useful are things like: reference cards, illustrations, extensive examples, sample sessions?
These are some of the questions in this short paper about (printed) documentation from Microsoft.
A focus group of thirty-four participants with varying computer experience were recruited to provide feedback on documentation on word processing, spreadsheets, database management systems, and programming language products.
Tutorials
- Everyone (including the programmers) want tutorials that show how to use the product or programming language.
- End-users also want tutorials for completing specific or common tasks.
Illustrations
- The programmers are mostly indifferent to pictures. End-users, however, want illustrations, especially program screenshots.
Reference
- Everyone agrees they want a "phone book" i.e. a book that tells everything about the product, including "tricks" and shortcuts.
- The programmers emphasise that any examples, especially sections of sample code, must include annotations to be useful.
Cookbook
- The cookbook includes models for solving many types of problems and for performing many types of tasks. (Interesting to note: in 1984 the term "cookbook" was a new, unfamiliar term in the context of documentation.)
- The "cookbook" potentially bridges the gap between tutorial and reference manual.
In conclusion, ideal documention looks like:
1. Tutorial
2. Cookbook
3. Reference
---
There is a lot more in the paper not included in the summary above. It's an excellent, readable paper. And it hasn't aged much despite being written in 1984.
Finally, the title of the paper "Those Silly Bastards" is a quote from a programmer who participated in the research. The full quote is included at the very end of the paper :-)