'Those silly bastards' : A report on some users' views of documentation (1983)

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

- 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.