Gissue freshening and UVIs

This is for fellow builders and project managers.

  • A gissue is a GitHub Issue, often called a ticket in other bugtrackers
  • A UVI is a user-visible improvement
  • Anki is a spaced-repetition system to help you memorize flashcards
  • A tock is a 45-minute pomodoro

Part One

Gissue freshening is important and powerful (and it seems like it’d be very hard to achieve without Beeminder yay Beeminder). I think of it like doing Anki on the backlog of open issues in our bugtracker. Every day, I have to grab the oldest 5 non-snoozed gissues from our backlog of (currently) 437 and freshen them. Freshening a gissue means improving it in some tiny way that makes GitHub update the last-modified date. That might include updating the labels, tightening the copy in the top-level description, clarifying the title, or adding keywords for easier future searching. If there’s nothing to improve and the gissue is still not a priority and I’m ok letting it go out of sight out of mind, I can snooze it by applying the “ZzZ” label to it.

With 437 gissues and freshening 5 per day, I’m cycling through the gissues every 87 days, so every 3 months. The biggest value in doing so is I mostly remember all the gissues. When we encounter bugs, I can find an existing gissue instead of creating a new one. That keeps the backlog from getting more and more overwhelming and crufty. Also I can add links in the gissue descriptions to related gissues – a common improvement to make when freshening.

Even without appreciably whittling down the number of open gissues, I feel drastically better about them than I would otherwise.

Part Two

A common and very fair objection we hear to UVIs is that they distract you from deep work and bigger features that can’t be built in a day. My opinion is that it’s worth the tradeoff. And normal companies can just dial the slope down until it’s not impinging on deep work. In our case I’m resistant because of some pretty huge don’t-break-the-chain psychology. We’re hitting 4000 UVIs around new years or so!

An idea we may try, to reduce the UVI burden/overhead, is doing UVI Fridays where we do hourly tocks and try to crank out 7 UVIs in one workday. Or usually fewer than 7 required since deep work typically yields UVIs too and we just need to average 7 per week. Again, if you’re not wedded to exactly 7 UVIs per week every week forever and ever, just dial the slope until the tradeoff feels right.

(We have a lot more thoughts on UVIs and something we call the Anti-Cobweb Principle. Expect another blog post eventually. There’s a very old one we still like in the meantime on my old blog.)

Part Three

I don’t know how to articulate this part yet but Part One and Part Two feel connected in that there are so many small issues that come up and it can feel discouraging and overwhelming how fast they appear and I don’t know how to triage them. But the UVI goal means steady pressure to pick up a lot of those and that feels like good and important pressure.

In conclusion, you should have a freshgish goal, as I call mine, to cycle through your backlog, touching and improving the oldest items. I actually do this for several things besides Beeminder’s main GitHub repository. Also you should absolutely beemind user-visible improvements to whatever your primary project is, if it has an audience of some kind. Steady visible improvement plus triage and not letting things go out of sight out of mind. And just scrolling through that changelog when you’ve built up years of history is immensely satisfying.


I don’t think this is actually a fair objection, for the following reasons:

  1. UVIs don’t have to be huge. Some of the weirdly impactful ones have not been – simple copy tweaks, for instance. There will always be small UVIs like this, opening up time for longer-term projects.
  2. UVIs don’t have to take developer time. Improving user-facing documentation is my job, for instance. If you guys wanted to do a big project, you could pass the UVI torch on to me for a week or whatever.
  3. Big projects generate multiple UVIs. With planning ahead, you can even lay out how many UVIs a project should produce and tweak your schedule accordingly.
  4. Working without any concept of UVIs and prioritising bigger features leads to the opposite problem. I see it at Lisa’s company all the time. The dev team, apart from the most junior (Lisa), are all on building new features. There is almost no time allocated for fixing bugs. Users feel that after a while. Moderation in all things is sensible: no one ever said you have to do a UVI every day for every business. In some places that doesn’t make sense, and that’s fine.

Dang, powerful points, @shanaqui. I’m extra sold now. @gbear605 asked another good question in Discord, about how much time we actually spend keeping the UVI graph happy vs doing deeper work. I think the boundaries are fuzzy and our time-tracking insufficiently fine-grained to answer that (TagTime tells me I’ve spent 55 hours so far in 2021 on UVIs but I think I sadly haven’t been consistent in how I’ve used the “uvi” tag so that’s curation and composing UVIs plus an unknown amount of actually working on UVIs).

Another way to measure it could be flipping through and seeing how many feel like they oughtn’t have been prioritized. Looking at the most recent 10…

  1. trello link to autodata source trello board – is nice, is a first step to doing this consistently across all integrations, but wasn’t crucial or anything. verdict: BAD UVI PRESSURE
  2. don’t throw away precision from withings – low impact but important to fix such things on sheer principle, plus got this done as part of working on a pet project. verdict: NEUTRAL
  3. tags via the API – @zzq#3035 did this for us. verdict: NEUTRAL
  4. garmin metric confusion – necessary. verdict: GOOD UVI PRESSURE
  5. API 500 error – embarrassing. verdict: GOOD UVI PRESSURE
  6. generalized previous fix – also embarrassing. verdict: GOOD UVI PRESSURE
  7. alignment/css problems with logos – embarrassing plus part of work on focusmate integration. verdict: GOOD UVI PRESSURE
  8. garmin units – part of doing the previous garmin thing. verdict: NEUTRAL
  9. kill / clean up the “donate” page – i was embarrassed by it so i declare it GOOD UVI PRESSURE
  10. menu goes away when you click off it – that’s been an annoyance for years and should’ve been done ages ago. verdict: GOOD UVI PRESSURE

In conclusion, I claim having the UVI goal is mostly amazing and definitely net-amazing.

Discussion of gissue-freshening ensued today (@bee’s now beeminding them too and I’m trying to convince @adamwolf) and we made this handy list for when Beeminder is making you freshen a gissue and you’re not sure what to do.

Start at the oldest non-snoozed gissue and, if it’s not obvious how to freshen it, go down this list until you find something that applies:

  1. More copyediting of the top-level description as you re-reflect on the gissue.
  2. Optimize the title for getting you to recall what the gissue is about.
  3. Are the labels good?
  4. Often you think of new keywords or related gissues to link to, based on other freshening.
  5. Move things from the comments to the top-level description.
  6. Split the action items into finer-grained tasks.
  7. Check one of them off or otherwise make some quantum of progress and mention what you did as a gissue comment.
  8. There’s always snoozing it if no freshening makes sense and it’s not a priority and is ok to go out of sight out of mind until we go looking for it.
  9. If you’ve exhausted the previous 8 things and are still agonizing, identify a pre-req gissue. Say you need to freshen gissue G and you’ve found gissue H that should happen first. Edit H to include “unsnooze G” as a checklist item, then snooze G.
  10. Whine to Danny (Bee’s words, not mine!) who can probably do one of the above things for you.
  11. If even that fails it probably means it’s time for the gissue to actually be the next priority!

(Note in particular how huge a release valve #8 – snoozing – is.)