Almost five years ago I released my first Rubygem, NullDB. It was based on ideas from a couple of other libraries, namely ARBS and UnitRecord. In the README I said:
It differs from them in a couple of ways:
- It works. At the time of writing both ARBS and UnitRecord were not working for me out of the box with Rails 2.0.
- It avoids monkey-patching as much as possible. Rather than re-wiring the secret inner workings of ActiveRecord (and thus being tightly coupled to those inner workings), NullDB implements the same [semi-]well-documented public interface that the other standard database adapters, like MySQL and SQLServer, implement.
- UnitRecord takes the approach of eliminating database interaction in tests by turning almost every database interaction into an exception. NullDB recognizes that ActiveRecord objects typically can‘t take two steps without consulting the database, so instead it turns database interactions into no-ops.
I wrote NullDB out of frustration with existing solutions. I was grumpy from having wrestled with the existing libraries and failing to get them to work. I was also proud of what I thought was a better solution. I wanted to tell the world: “look, my way of coding this solution is better, and I’ll tell you why”. I wanted recognition. I wanted to prove myself. And it worked. None of my gems have ever been (or deserved to be) wildly popular, but of the bunch, NullDB is still probably the most used.
Sometime after I wrote the README, a colleague read it and said something like “wow, you were really pissed off when you wrote this”. I said “heh, yeah” and laughed it off.
Last night I read it again. Then I performed a little thought experiment. I imagined myself meeting Dan or Jay at a conference, shaking their hand, chatting for five minutes… and then writing that same bullet-list about how NullDB was different from better than their library.
In my head, it didn’t happen. I couldn’t see myself writing those same lines, in the same tone, if I had conversed face-to-face with the author of ARBS or UnitRecord for just five minutes.
NullDB was still a better solution, technically, for the problem I was solving at the time that I wrote it. But the tone I used to introduce it was unnecessarily harsh and combative. I could have said the same things in a kinder way.
I pour part of myself into the code I write. My code is, in part, a representation of me, and that extends to the documentation. And those three paragraphs portray a kind of person I don’t want to be. That I am trying not to be.
I don’t know if Dan Manges or Jay Fields ever read those words, or even know about NullDB. But in case you are reading this: Dan, Jay: Your ideas made NullDB possible. I’m sorry I chose to introduce NullDB the way I did. My tone was uncalled-for. I have very belatedly updated the documentation to be less confrontational. I owe you both beers the next time I see you.
I like the idea of imagining yourself meeting with the developers of libraries you had problems with and thinking about how that would influence your choice of words. However, I don’t necessarily think that a little subtleness and emotion is a bad idea for READMEs. Sometimes developing software IS just emotional, frustrating and by describing the problem “with a wink” people are more likely identifying themselves with your situation and know where you’re coming from.
Apart from that, reading not-only-rational/bald documentation is just more fun 🙂
Good job on recognising this in yourself. More and more, I’ve found myself doing the same thing anywhere I post on the internet, and I ask myself, “Does this post increase the net worth of the internet? Is this who I want to be?”. If the answer to those questions is no, I don’t post it. As you point out, it’s easy to give our emotions free reign when we communicate with the anonymous blob that is the internet, and it takes some willpower to force ourselves to think about the real people who might read it and the impression it might give.