Contributing Without Code

Writing documentation is relatively easy. Writing clear documentation is hard. Writing clear documentation and ensuring it stays up to date is, if not an order of magnitude, at left several times harder than doing the same thing in code. To the point where it's less effort to re-answer the same questions over and over in an issue tracker (and others can help keep track of your responses) than to maintain up to date docs.

My preferred approach, on smaller projects with limited numbers of people, is to push documentation as close to the code as possible. Prefer comments, tests, and types over standalone docs, in that order. Prefer not to duplicate the code (explain why, not what, is being done; consider using intermediate variables with descriptive names rather than a comment on "what"), unless it is a public interface and you want to restrict the intended behavior to some subset of the actual behavior. Your standalone docs are now about the high level stuff, filling in the gaps between file-level comments and directing the reader to the right files/code to look at. Generated documentation from the types and comments helps make this approach more readable.

Here's an example: a project I'm working on now had several shell scripts to automate common tasks (e.g. setup). Each script starts with:

    #!/bin/sh

    usage()
    {
    cat >&2 <<'USAGE'
    Description here
    USAGE
    }

    set -eu
    trap 'test $? -eq 0 || usage' EXIT

It's a travesty that this is not the norm for major open-source projects.

> Moderators and a small number of reviewer users comb the depths of /newest looking for stories that got overlooked but which the community might find interesting. Those go into a second-chance pool from which stories are randomly selected and lobbed onto the bottom part of the front page.