A tweet thread on why it's probably a good idea to document your open source project. 1/18
Recently, I had an online interaction with a brilliant programmer who contributes a lot to open source projects. A while ago, I found myself faced with a piece of software they had written which no longer worked. 2/18
I absolutely *needed* that piece of software to finish a crucial research project. So I tried desperately to fix it. And I couldn't fix it. I tried for a couple of weeks solid, but I couldn't. 3/18
It was complicated, had a bunch of moving parts, and frankly I'm just not that smart, while the original author is quite frankly (based on their body of work) a genius. (I'm quite serious about that.) 4/18
The library in question was also almost completely undocumented. That was the key. A README or two, probably an hour's worth of work dumping content from brain into text, and this wouldn't have been a problem. I needed a map to a strange territory but there was none. 5/18
So I asked the original author for help. And they told me, with complete justification, that they had no time to spend on it, they no longer used the language or platform in question. They were entirely polite, and entirely reasonable. 6/18
So I abandoned many months of work, and re-wrote a lot of my project in an entirely different programming language, and moved on with my life. It cost me dearly, I couldn't really afford the time, but I did it anyway, because I had no choice. 7/18
A long time passed. I still felt icky about it. In a moment of weakness, I mentioned this to the original author. They got angry, and said, approximately, "this is why I often regret contributing code, people feel entitled to your help forever afterwards." 8/18
And their complaint was totally reasonable. Just because you contributed something to the world, for free, does not mean anyone at all is entitled to your time. No one is *entitled* to charity from others. No one is *entitled* to documentation for open source software. 9/18
However: generally, when I write open source software, I do so hoping other people will use my code. I always document everything, in as much detail as I can, because I know how hard understanding code can be, and how sometimes it's too much and people give up. 10/18
Imagine you're starving in the wasteland and you come across a crate of canned food. Inside is everything you need in the world, but *you have no can opener*. You're inches away from what you need but you can't get at it. 11/18
Putting out useful and complicated software without documentation is like shipping canned food to hungry people without a can opener. Yes, sure, you weren't obligated to send them the food at all. But didn't you send it so they could eat the food? 12/18
And yah, it's annoying having people expect more free stuff from you when you already did something nice for them. I strongly believe people truly have no right to demand that you do anything for them. But don't you *want* your contribution to be useful, to be used? 13/18
And yes, sure, with a lot of effort, some smart people will read your code and puzzle things out and move forward. But you could have saved all those people many hours of their lives, and weren't you trying to do that in the first place? Didn't you want to help them? 14/18
I rarely feel this sort of regret about contributing open source software because I document it. No one is entitled to documentation, but I want others to use my software. And documentation also means fewer people ask questions later. 15/18
So I'm *not* telling any of you that you should feel obligated to help the users of your code by documenting it. No one is entitled to documentation. No one is entitled to your time. They should, *truly*, be grateful you gave them anything for free at all. 16/18
But if you're working on a really complicated artifact, every hour you spend documenting what's totally obvious to you will probably save someone coming after you many hours of pain. Wouldn't it be *nice* to know that you made your software that much easier to use? 17/18
So may I suggest, in the strongest possible terms, that if having other people use your work motivated you in the first place, it would be *nice* of you to write a README or a manual or what have you? So everyone, please, document your code. 18/18
