flexibeast.space - gemlog - 2022-07-25
On telling users to write the documentation themselves
i occasionally encounter a situation in which foss users, noting or complaining about the lack of documentation for a piece of software - whether an end-user application or a developer library - get told by the software dev(s) to write it themselves.
This feels ridiculous to me. Someone reaching for documentation is doing so because they don't know how to use some software, whether an application or a library. Since they don't know how to use the software, they are not able to document how to use it!
Presumably the idea is that application users should faff around, experiment, find what works and what doesn't. And that library users should do the same, or read the library source. There are a few problems with this:
- The usual reasons the user has reached for the software is because they feel it's going to help them Get Something Done, or because they've been forced to use it by the-powers-that-be - not as an end in itself. Someone frustrated by not being able to progress their task due to lack of documentation is unlikely to have their frustration reduced by being told to go off-task.
- Users might come up with a solution, but that doesn't mean it should be documented: that solution might not be idiomatic, or indeed, it might be actively dangerous. This is exemplified by users who, when faced with permissions issues on *n*x-ish systems, ‘solve’ the problem by setting files (or entire directory trees!) mode 777, sometimes creating massive security holes.
- The source might be written in a language with which the user isn't familiar - cf. many programming languages providing ‘wrapper’ APIs around C libraries.
Some devs make the argument that if they spent their time writing documentation, they wouldn't have as much time to work on the software itself, or that if they had to write documentation, it would decrease their enthusiasm for working on the software overall[a]. Okay; they get to choose how to spend their time. But that doesn't necessitate telling users to write the documentation themselves! Devs could simply say e.g. “I find working on documentation to be too much of a chore, sorry.” And preferably: “.... but I'll try to support you if you'd like to work on it yourself.” (As someone who can actually like writing documentation, i've found it frustrating when i try to do so for a given project, only to face a lack of concrete support from the relevant dev(s).)
At any rate, i use a dev's attitudes towards documentation as something of a measure of how supportive they are of users, and the extent to which i should rely on their software. A dev who would rather avoid spending five minutes on writing documentation, rather than effectively forcing (say) five users to each spend five minutes trying to work out how to do something, certainly has the right to do so; but then i have to weigh up whether the benefits of using their software will outweigh the possible costs when the software becomes a hindrance rather than a help.
Larry Wall, creator of the Perl programming language and patch(1), wrote that the first of the three great virtues of a programmer is ‘laziness’[b]:
The quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful, and document what you wrote so you don't have to answer so many questions about it.
☙
☙
[a] And there are possibly other reasons as well:
The vast majority of my time as a documenter of groff is spent on the discipline of crafting English, not markup.
But you can't get this message through to a lot of people. Writing English doesn't seem to them like something that will impress anyone reading their résumé. And, to be sure, for a lot of the people they're trying to get jobs from, they're right.
— https://lists.gnu.org/archive/html/groff/2022-07/msg00143.html
[b] The other two great virtues are ‘impatience’:
The anger you feel when the computer is being lazy. This makes you write programs that don't just react to your needs, but actually anticipate them.
and ‘hubris’:
Excessive pride, the sort of thing Zeus zaps you for. Also the quality that makes you write (and maintain) programs that other people won't want to say bad things about.