3 ms·

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

hazelnut-tree 4y ago
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.

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.