5 ms·
Like the "What nobody tells you about documentation" post that was going round recently, this one says that the way to write your "final source of truth" docume
by mjw1007 7y ago
Like the "What nobody tells you about documentation" post that was going round recently, this one says that the way to write your "final source of truth" documentation is to document each individual function and assume that that adds up to a complete description.
I think this is often bad advice. It's too easy to find documentation of this sort that misses out describing key aspects of how the software actually promises to behave.
For example, you might have a graphics library with lots of functions for creating pens and coordinate systems and so on, all meticulously documented, and then one "render" function with a brief description that tells you what the return type is, but no description of (say) the layering or composition model, because that doesn't belong to any one function.
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.
- forgotmypw 7y agoCould you link to that post, please? I googled, but didn't find it.
- shadowfiend 7y agoOne of my favorite writings on the matter is Teach, Don't Tell, by Steve Losh: http://stevelosh.com/blog/2013/09/teach-dont-tell/ http://stevelosh.com/blog/2013/09/teach-dont-tell/ , including a rather savage takedown of wikis as a documentation mechanism. A bit idealistic, perhaps, especially for open source or single-person projects, but a good north star for doc work IMO.
- mjw1007 7y agoIt's good advice, but I think that like a lot of such articles it's talking about how to run, when there's a need for more articles on how to walk. That is, the first duty of technical documentation is to be complete and correct (at least for practical purposes). Once you've got that far it's time to pay attention to optimising it for the needs of your likely readers.
- 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!
- kaycebasques 7y agoIn my experience (as a technical writer) the best documentation approaches it from both angles. The top-down approach connects all the pieces together, as you mentioned, and the bottom-up approach gives the nitty-gritty details that implementers need. That's why conceptual overviews and references are 2 of the most common content types. See also this previous comment of mine about a common pitfall of reference documentation: https://news.ycombinator.com/item?id=20473713 https://news.ycombinator.com/item?id=20473713
- mntmoss 7y agoI think the main error I see when developers try to create a lot of docs, vs the most common "uniformly underdocument", is to get twisted in a pretzel over what point or detail to include when, eventually splattering all of it into one form(whether that be tutorial, API reference, or some other idea) while still not covering everything because when you explain everything you eventually end up crossing over into being a programming tutorial. The more systematic approach which I've really caught onto recently is to assume it has to be atomized a bit to get any breathing room. Make distinct spaces for the narratives, spaces for basic concepts and references, spaces for formal overviews, and spaces for single tasks, features and APIs. Then have them link to each other, using the link as the leverage to let each part of the documents use the necessary vocabulary without overexplaining. While it's possible to overdo that and produce documentation that is a thicket of links, just clarifying that you have a distinct purpose to the space makes the writing process much more systematic - no confusion over what the writing needs to concentrate on.
- jerf 7y ago"document each individual function and assume that that adds up to a complete description." Every major system for converting function documentation to code has a slot for documentation at the top of the module/package/class/whatever. I find this is very underused, almost across the board. I actually quite like automatic documentation, on the provision that you put something decent at the top for people to orient with.