1. 52

  2. 8

    This is good, though I think I could live without how-to guides. Two problems. As a developer, you end up with a class of users who are paralyzed unless you hold their hand the whole way. As a user, a lot of times it seems too much effort is spent on how-to, though that might improve if more people read this article.

    1. 9

      I’ve found that how-to guides are helpful exactly because of paralyzed users (especially fellow devs) and non-paralyzed users (eager juniors or impatient seniors), at least in the context of ops or certain mechanical refactorings or periodic additions to the codebase.

      At 0300 having a runbook for bringing up a fallen DB, or having a how-to for certain common-but-not-yet-automated data remediation tasks is invaluable, especially when it explicitly gives the One True Way of accomplishing something and notes error conditions and when to go find an adult.

      That’s probably my biggest disagreement with that part of the article–I don’t think how-to’s should leave any ambiguity for the end-user…it should be one pass away from a shell script.

      1. 11

        I would argue this is a UX failure. If sufficient number of users need to perform exactly the same steps to accomplish a task, then it is the software that should make that possible. The canned recipes should be built in, not copy pasted.

        1. 2

          In theory, you’re correct and I fully agree. In practice, it is often a matter of prioritization. I often end up coding the steps once I’ve been annoyed often enough. This is also directly proportional to the complexity of the steps. There’s also the “corporate” aspect of it, which is where I encounter this most: this kind of thing is often not a priority unless it happens often enough to bother a significant amount of users in a significantly short time.

          1. 1

            Agreed in general case, and that’s exactly how many of our automation scripts came to be.

            That said, for certain sensitive and infrequent tasks runbooks are faster and safer to write than scripts. Ideally those runbooks are translated into scripts when the time comes.

      2. 8

        Note that this was reverse-engineered from Django docs; here’s a document explaining “here’s how Django decided to organize docs” without the reverse engineering— https://jacobian.org/writing/what-to-write/.

        (Separately: I really love this particular writeup.)

        1. 3

          Doesn’t look like a bad advice, but doesn’t look like good either.

          First of all there’s not an absolute “4 different functions” your documentation should fill. You better decide the structure by which is appropriate for the software, not follow a guide that tells you what you should do.

          Also I don’t think that the post tell the thing what I think is important in good documentation. What I keep important is that the internal documentation and the code are either tightly linked together, or that the documentation flows upwards from the code. Eg. You document internals, then you document the features they provide and finally provide examples and everything else. This guide seems to start with things I’d leave last.

          1. 8

            I think the post addresses that by distinguishing between documentation for the project and documentation about the project. Some of the worst documentation I’ve dealt with tried to repurpose the former as the latter.