'Those silly bastards' : A report on some users' views of documentation (1983)(dl.acm.org)
dl.acm.org
'Those silly bastards' : A report on some users' views of documentation (1983)
https://dl.acm.org/doi/abs/10.1145/800060.801172
https://dl.acm.org/doi/abs/10.1145/800060.801172
- 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
- Programmers are mostly indifferent to pictures (I wonder if this is true today among programmers?). For end-users, illustrations are essential - 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, but today is a familiar documentation pattern.)
- 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 detail in the paper. This an excellent, readable paper. And it hasn't aged much despite being written in 1983.
Finally, the title of the paper "Those Silly Bastards" is a quote from a programmer who participated in the research. From the paper:
> I want to finish by explaining the title of this paper - "Those Silly Bastards." During the focus group on programming languages, one of the programmers said:
They obviously are trying to give you something, but those silly bastards don't know what they are trying to do. Just give us a complete, accurate manual that tells us everything we need to know.
> There's a pep talk for you.