If you read this blog, then you know that I evangelize proper documentation with zeal more commonly associated with religious crusades1. I’m here to tell you today that I have received a sign.
Someone noticed
Apparently I have an academic fan? This was novel and unexpected, but at the closing beach bonfire for the T2T F2F meeting, someone came up to me and went, “You’re Faith! The one with all the good PRs!”
I don’t think it’s an exaggeration to say this was one of the proudest moments of my life.2
Because yeah, I am the Faith with the good PRs. Or at least I try to be. I’m
the gal who makes tiny quality-of-life PRs about (to pull a few
examples from tomorrow’s release) “vg snarls --traversals related helptext
improved and useful errors added” or “vg construct -S will automatically turn
on -f (resolves #2932)”3. Things that, sure, don’t need to be
done, but that will make life smoother for the next person.
It meant a lot that someone noticed.
Someone cared
And not only did this person notice that I’d been polishing around the edges, they explicitly voiced that it had been useful for them. I wrote on this blog around a year ago:
Improving usability is, far too often, nobody’s job. Scientists have a rather bad habit of making code that works for us, writing a paper, releasing a link into the wild, and then… moving on to the next project.
I am perfectly aware that my usability updates won’t get me more papers. That was never the point. The point was to make the tool more usable. And here was a user telling me unprompted (even more, having sought me out) that it I had, in fact, made the tool more usable. That they had benefited from my work.
It worked
And now for the real mother lode: not only did someone notice that I was trying, and not only did they care, but they complimented the results. The following is a paraphrase from memory:
“You turned that messy academic software into something professional. I had been planning to work to be the only one in my lab who understood how to use
vg, and then you came and took away my added value. Amazing.”
And that independent confirmation that my goal of well-documented software had at least gotten decently far along its way there? That was worth more than ten papers, to me.4
So I’m here to tell you, my fellow workers in the documentation mud pits: the work is not in vain. Keep at it. You’re doing great.
- One more for “things I’m better at evangelizing than my own religion”. The previous one being the game Roll For Shoes.
- Granted I have a relatively short life so far to draw from.
- The PR which fixed this was #5007, made over six years after its idea was mentioned in an issue thread.
- Somehow I suspect that it won’t be worth more than ten papers to hiring committees, but alas, such is life.