4 ms·
> Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then tryin
by l_t 7y ago
> Instead, I recommend starting by documenting the key behaviour of the program, describing its model of the world and defining terminology, and only then trying to document each function in terms of that model and terminology.
Can you explain in more detail how that's different from the approach described in "What nobody tells you about documentation"? [0] At first blush, your recommendation sounds pretty similar to what is suggested in that post.
Is this a critique of the guideline to "Give reference documentation the same structure as the codebase" that was in [0], or is it more like you think the importance of the "Explanation" section is underrated?
(This is coming purely from the perspective of somebody who is trying to write better documentation. I'm not trying to defend any particular stance, just interested in your opinion.)
[0]: https://www.divio.com/blog/documentation/ https://www.divio.com/blog/documentation/
- mjw1007 7y agoI think there are two "axes" here: One is: - A: a list of functions or similar items, vs - B: a description of a model, its operations, and terminology The other is - X: "the only job is to describe, as clearly and completely as possible", vs - Y: "a chance to relax and step back" My reading of the "what nobody tells you" article is that it envisages a reference which is A and X, and an explanation which is B and Y. I recommend that the reference should be A, B, and X. Having an explanation which is B and Y is a fine thing too. So basically the bit I don't like in that article is where it says the reference should not attempt to explain basic concepts. Maybe it doesn't need to try to teach concepts, but it very often does need to define them. (Also, I think rationale fits well in the "describe as clearly and completely as possible" document, especially if you're in a position to separate it a bit from the main text.)
- l_t 7y agoAh, that makes a lot of sense. Thanks for the very clear explanation! It makes me think perhaps that's one of the things that the Postgresql docs are so good at -- hitting that "B+X" quadrant in their reference docs. I'll definitely keep that in mind!