evan @IrrationalMethod@social.coop
Quiet public

@mattlyMatthew Lyon

What the documentation ought to cover. I read Mythical Man Month (the other essays in the book too) a few years back and was struck how clearly this is laid out there.

I'm not saying it is an amazing book*, but a lot of his (technical) observations from the 60s and 70s certainly still apply.

(*Warning: there's a small sprinkling of cringy social commentary in the book too)

(From web.eecs.umich.edu/~weimerw/20)

Screenshot of PDF (some detail bits omitted for size, from page 165 of linked document.) What Documentation Is Required? Different levels of documentation are required for the casual user of a program, for the user who must depend upon a program, and for the user who must adapt a program for changes in circumstance or purpose. To use a program. Every user needs a prose description of the program. Most documentation fails in giving too little overview. The trees are described, the bark and leaves are commented, but there is no map of the forest. To write a useful prose description, stand way back and come in slowly: 1. Purpose. ... 2. Environment. ... 3. Domain and range. ... 4. Functions realized and algorithms used. ... 5. Input-output formats, ... 6. Operating instructions, ... 7. Options. ... 8. Running time. ... 9. Accuracy and checking. ... Most of this document needs to be drafted before the program is written, for it embodies basic planning decisions. To believe a program. The description of how it is used must be supplemented with some description of how one knows it is working. This means test cases... Every copy of a program shipped should include some small test cases that can be routinely used to reassure the user that he has a faithful copy, accurately loaded into the machine. Then one needs more thorough test cases, which are normally run only after a program is modified. These fall into three parts of the input data domain: 1. Mainline cases that test the program's chief functions for commonly encountered data. 2. Barely legitimate cases that probe the edge of the input data domain, ensuring that largest possible values, smallest possible values, and all kinds of valid exceptions work. 3. Barely illegitimate cases that probe the domain boundary from the other side, ensuring that invalid inputs raise proper diagnostic messages. To modify a program. Adapting a program or fixing it requires considerably more information. Of course the full detail is required, and that is contained in a well-commented listing. For the modifier, as well as the more casual user, the crying need is for a clear, sharp overview, this time of the internal structure. What are the components of such an overview? 1. A flow chart or subprogram structure graph. 2. Complete descriptions of the algorithms ... 3. An explanation of the layout of all files used. 4. An overview of the pass structure—... 5. A discussion of modifications contemplated in the original design, ...
0
0
0

If you have a fediverse account, you can quote this note from your own instance. Search https://dragonscave.space/users/x0/statuses/115175389395520150 on your instance and quote it. (Note that quoting is not supported in Mastodon.)