This is a sequel to the previous post on Backlog Freshening. It’s been gratifying to hear testimonials from you all about how valuable you’ve found this — for tasks in TaskWarrior, songs in one’s piano repertoire, and of course issues in GitHub. By popular demand, here’s Support Czar Nicky with the story of how they use the same technique for keeping Beeminder’s documentation up to date. You’re welcome!
The previous post ended with a small blurb about how Danny’s idea of freshening a backlog isn’t just useful for programmers… leaving the floor wide-open for me to come in with my freshening experiment! I say “experiment” but, even though I’m not done with my first passes through the relevant backlogs, the process is definitely here to stay.
You’re hopefully aware that Beeminder has a whole set of help docs that go in-depth on how things work, give extra examples, walk folks through goal set-up with certain integrations step-by-step, etc. (If this is complete news to you, then holler! We need to know when we’ve buried something important.)
We also have a set of behind-the-scenes docs, which tell new workerbees (or forgetful ones) exactly what we need to do when X or Y circumstance comes up.
The problem with documentation is that it’s really easy for it to get out of date — especially when you make a user-visible improvement once a day, seven days a week, 365 days a year, 3650 days a decade… It may not seem like a big deal when it’s just a tiny tweak in copy. People would totally know that the “Ratchet!” button is the same as the “Ratchet” button but with more enthusiasm. The problem is that the slow drift is insidious, and before you know it, none of the words on the page match anymore! And fixing it all up becomes a never-ending task: I look at the task of “updating the Help Docs” with a bit of a sense of despair. I know it all needs work, but I don’t know where to start.
Or I didn’t — and now I do. Once Danny started everyone off with the idea of freshening the open Github issue backlog, I decided to apply the same to the Help Docs (and the internal support documentation as well). Alongside big edits like adding in new articles for new integrations, or adjusting all the mentions of the word “road” to “red line”, every day I look for the oldest unedited Help Doc and the oldest unedited support document, and I do something that improves them.
At the moment, I’m on my first pass with both. Because the process of ascertaining which one was the oldest took up so much time, I actually simplified it: for my first time through the whole backlog, I’d just go in the order they’re listed. In the future, I can just follow that order: that will automatically be (more or less) the right one. (There will be exceptions where a single document here or there has been edited more recently, but it could probably do with other edits anyway if it was just edited to match a recent change, rather than with an eye to improving it overall.)
And how’s it going? Well, at the time of writing, I’ve edited about 80 of each, producing about 50 UVIs. The improvements I’ve made aren’t all huge: sometimes it’s just a word or two. Sometimes it’s important stuff for accessibility, like adding alt text to images where it was completely lacking before. Sometimes it’s pretty big, and involves me poking around trying to find out if certain things have changed, or whether things work the way I think they do.
It’s not always easy, and personally I do encourage some flexibility — if something is going to take you a couple of days to properly attend to, then do another, easier document first, to give yourself the time to do a proper job on the bigger edits. You can’t slack on making the big updates, either, no matter how tempting it is to wait until the document comes up for freshening.
Don’t skimp when you know something needs fixing, either: you can’t just wait for the backlog freshening to make you get round to it. Freshening helps you get to the stuff that didn’t seem important to change at the time, and is no replacement for fixing something that suddenly becomes egregiously wrong. It helps you get to the stuff that you didn’t know about yet.
What happens once your help documentation is absolutely perfect? Well, the good news is, that will never happen for something that documents a site in active development. I totally expect to get to a point where some of the docs don’t need anything obvious tweaked, though. In that case, I’ll close-read them, be nitpicky about the copy for absolute clarity, ensure they have the right keywords, and then call it a day. I’m pretty doubtful that there’ll ever be a document that has not even a comma out of place.