
Essential elements of good documentation - curiousorchid
https://www.sohamkamani.com/blog/how-to-write-good-documentation/
======
mjw1007
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.

~~~
l_t
> _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
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.)

~~~
l_t
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!

------
slowmovintarget
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/](https://www.divio.com/blog/documentation/)

~~~
dang
Discussed here:
[https://news.ycombinator.com/item?id=21289832](https://news.ycombinator.com/item?id=21289832)

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

------
m463
What I look for most in documentation: examples.

------
kaycebasques
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/](https://web.dev/handbook/quality/)

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

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

~~~
JadeNB
> 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](http://stevelosh.com/blog/2013/09/teach-dont-tell) linked elsewhere
([https://news.ycombinator.com/item?id=21339009](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.

------
abductee_hg
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! :)

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

------
rammy1234
was this written by react devs ?

