I don't exactly dislike writing documentation, and I don't at all mind the effort and thinking that it takes, but I just hate how much time it takes to write documentation even remotely well.
And it's frustrating because in a very important way, the person who wrote the code is the worst person to document it. So the time inefficiency is very high.
The best person to document software is someone eager to get an informal explanation from the person who wrote it.
When I have just written a piece of software, I am literally mentally as far possible from someone who needs the documentation. I know exactly what my software does. I don't have any questions. All features, quirks, and caveats of the interface and any side-effects are equally unsurprising.
To assume the perspective of a person who actually needs to be helped by the docs, to see what could be better with the docs, is far more expensive to the fresh author than anyone else.
I often have set my software aside long enough to start forgetting what it does, or go through several rounds of trying to explain it to others, before I can see what the docs need to be - any docs I previously forced out of myself are usually revealed to be bad once that happens.
I do seem to be getting better at that... the first pass of README for my Python macaddress library still holds up after a few years, I think.
But even so, it's exhausting how time-consuming it is. Does everyone have to take this long? Probably not, but it just rarely comes easy for me. I have to write stuff, re-read it a little bit later, a little fresher, while trying to put on a different mental angle, see flaws - the misinterpretation potentials, the omissions of why it matters, spots where detail or focus is unnecessary, engineer a different wording or examples, rinse and repeat.
And it feels frustrating to not spend that time now, to just put it aside and not force it until one day suddenly the explanation flows... Because documentation is the main step between done and Done - between having a thing that works and any actual benefits of a having thing that works which involve other people. Because if I don't force it, something really nice like git-cotree will just sit indefinitely - sharing things doesn't actually accessibly share it with anyone unless you also explain/present/demo/market it.
janainaart
yousharknotpass
theartofmadeline
dededos
