Essential elements of good documentation | Hacker News Reader

Essential elements of good documentation

sohamkamani.com

123 pointscuriousorchid22 comments

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.

Could you link to that post, please? I googled, but didn't find it.

https://www.divio.com/blog/documentation/

Discussed here: https://news.ycombinator.com/item?id=21289832

One of my favorite writings on the matter is Teach, Don't Tell, by Steve Losh: 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.

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

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

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

Ah, 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!

In 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

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

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

This could be "How to write good project documentation" in GitHub.

I prefer the more general approach to documentation given here: https://www.divio.com/blog/documentation/

Discussed here: https://news.ycombinator.com/item?id=21289832

I appreciate it when creators provide introductory material in a top-down, inverted pyramid style. When I’m reading that sort of documentation, I am probably investigating tools for solving a problem and perhaps comparing different options. A quick summary that confirms I’ve found the right sort of thing — or that warns me immediately if I haven’t — and that sets out its distinguishing features and priorities is helpful. Following that with an overview of the main concepts and structure with some concise examples of typical use cases gives a flavour of what it’s like to use this tool in practice and provides some context for any larger examples or more comprehensive reference material.

This starts right from the first sentences describing the tool. I am a particular fan of people who don’t hide the purpose of the tool behind several lines of adjectives and credits. The Redis description in the article is exemplary, IMHO.

What I look for most in documentation: examples.

On web.dev we've started to create documentation quality guidelines [1] and a concrete, step-by-step checklist for ensuring that each document meets our quality guidelines. Long-term plan for the guidelines is to prioritize them based on research, and to link to research justifying why each guideline maps to quality. Feedback welcome, and LMK if you know of any other "style guides" already doing this.

[1] https://web.dev/handbook/quality/

[2] https://web.dev/handbook/content-checklist/

I think the important question to answer is actually why should you produce good docs. Is it to inboard new devs quicker? To help experienced devs find information faster? To act as a first line of support to reduce questions from third parties using your API? Maybe a bit of everything?

It'll vary from project to project depending on the audience. There's no such thing as definitively "good docs" that would work for everyone, but you certainly can make good docs for a given project if you know what your audience needs. Ask that question first.

> I think the important question to answer is actually why should you produce good docs.

I know it's not quite your point, but the article http://stevelosh.com/blog/2013/09/teach-dont-tell linked elsewhere (https://news.ycombinator.com/item?id=21339009) proposes:

> The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.

i am just going to throw in 2 points from my personal experience:

1) "negative space": tell people also "what it's not" to avoid misconceptions

2) keeping documentation updated with code

discuss! :)

The proposed structure is not entirely dissimilar to good old manual pages.

was this written by react devs ?

Reply on news.ycombinator.com