Sam’s Epic Quest for a Software Change

Recently, a developer friend shared this bit of insight. I can’t take credit for this, but I got their permission to share (after removing some things.) This is a great example of bridging the gap between business development and software development at a company. If you’re a developer and you want to communicate your process to the non-developers at your company, feel free to share this post with them.

Chapter 1 — The Grand Typing Event

Sam works for a startup, and has a really kick-ass idea for how the software should work differently. It doesn’t matter if it’s a bug or a feature, a tiny font change or a whole new platform, an idea he came up w/ himself or a request from a customer. The journey always starts the same. He goes to Github and starts typing:

When logging in to our software a popup should tell you you’re a already a member.

But then thinking back on all the times the CTO yelled at him, he recalls the following advice…

It’s more important to describe what’s wrong/undesirable about the software as-is than to describe what should be done to fix it.

So he changes it to:

If a user is new to our software, they type in their email expecting to register. But then are prompted for a password, not realizing the our software network is tied to another domain. Figure out a way to clarify to them why they’re being prompted for a password instead of a registration screen.

Satisfied with his description he thinks about the labels. Do any of them apply?

  • our software — Yes, this is a our software related request.
  • Security — No, there isn’t a security issue here even though it’s login related.
  • UI/UX — Yep, this is definitely a user interface issue.
  • Bug — Yes, arguably this is a bug, not a new feature.
  • Business Priorities — I don’t know! Can I justify this label to the CEO?
  • Critical — No, this is not a “wake the developer up at 2am” issue.

Sam takes solace in the fact that if he puts the wrong label on, it’s no big deal. And then submits his issue.

Chapter 2 — Crossing The Sea of the Unassigned

“OMG” Sam thinks. “There are 400 open issues. Is anyone ever going to see it? When will it be done? What’s going on?”

Valid questions. Most companies have more ideas than developer hours to work them. By definition not everything will be worked. But while we wait, let’s cover the life cycle of an issue:

  1. New! — Just entered by the reporter.
  2. Assigned — A developer has picked up the issue and started analyzing it.
  3. PR Created — A “pull request” is a proposed software change to be reviewed by the dev team.
  4. ​It can then either be accepted or rejected. If rejected, it’ll be labeled “Do Not Merge” and sent back to the developer for further work.
  5. Closed — The “pull request” has been accepted and the issue closed, as it has been resolved in the code repository.
  6. Deployed — The change has been pushed to production and is ready to use. It’ll be in the “company deployment” email.

All of these events trigger email notifications. “What’s going on with my issue?” is a question that should nearly always involve looking at the issue on GitHub. All the information is there.

So when is my issue going to be assigned?

There is no single person who should assign issues. That person would be both a bottle-neck and a single point of failure. For 95% of issues, a developer should self-assign. When self-assigning, developers have a broad mandate of “maximize my value to the company”. They take into account such information as:

  • What’s the labeled priority? (Is it labeled Critical? Business Priority? Low Priority?)
  • How critical do I think it sounds?
  • Do I have experience w/ this part of the code? (Will I be efficient working on it?)
  • Are there any upcoming cost events?(*)
  • How old is the issue?
  • Can this be easily folded into anything else I’m working on?
  • How much time do I have to work something?

And they each make individual calls on which issue will give the company the best bang for their developer-hour-buck. And they keep in their heads what the CTO has told them many many times: “It’s better to make a decision I disagree with than to wait for me to make it for you.”

So the short answer is: No one knows when it’s going to be assigned, if ever. But high priority stuff gets a lot of attention.

But our customer really needs this. They have a thing coming up. I need to know when this is going to get done.

Not really… You don’t need to know when it’ll get done, you need to know if it’ll get done before “the thing”. This is what we refer to as a “cost event”. IE: If this is not done before x point in time it’ll have y cost to the company. That y can range from “our customer is annoyed” to “our customer is going to cancel the contract”.

Cost events should be documented in the issue. CLEARLY, in BIG BOLD LETTERS. Create a milestone in GH if it’s a big one, or there are several related. They weigh heavily into a developer’s prioritization process.

Hey look, while reading this, you got an email saying your issue was assigned! Congrats!

Chapter 3 — The Valley of the Questions

If you wrote a clear and concise issue, you’ll likely hear nothing from the developer after they self-assign. Congrats! Writing an issue that is workable without additional information is hard — have you considered a job in software development?!?

More likely, the developer will ask some questions. You may get an email alert asking “Do we care if the user has logged into our platform recently?” Try to respond in the issue if possible. HAVING AN ARCHIVE OF WHY WE MADE A CHANGE IS IMPORTANT. People come and go (vacations/etc), and are generally forgetful. Discussing WHY a change was made in the issue is extremely valuable in the weeks/months to come when someone else is asking “WTF why does the software do this?”

Responding in the issue is also important for another reason: Developers work on more than one issue at a time. When they need clarification they ask it in the issue, and pick up a new issue in the interim. They likely won’t be working on it or thinking about it right when you’re responding, so calling / slacking / walking to their desk is likely going to interrupt some other work. Reserve that for when you believe there has been miscommunication, rather than using it as the primary way to respond.

If it’s a more complicated question, the dev will likely schedule a meeting. (Formally or informally as a “can we chat about this?”) THE RESULTS OF THAT MEETING MUST BE PUT BACK INTO THE ISSUE, by either you our the dev. For the same archiving reasons.

Once a developer has gathered all the information they’ll likely go dark while working on the issue. You’ll possibly see cryptic email alerts. ​You can largely ignore them, confident that work is progressing.

You’ll also likely get screenshots added to the issue if it’s UI related (and most issues are). Look over these carefully. Raise any concerns about the screenshot back in the issue.

Chapter 4 — Demo Day

If the issue is small / straightforward, this is likely skipped. But for anything major, expect a call from the dev saying “hey can I show you this thing?” or “here’s a link to test this out — let me know if you have any questions”. Take the opportunity. If you provide no feedback, likely it’ll get deployed as-is.

What the heck?!? This isn’t what I asked for in the issue!!

Possibly. Remember that part of “describing the problem is more important than detailing the solution”? If a developer is confident he has a better way to solve the problem than what was requested, he/she may have given you that instead. (CTO’s reminders of “it’s your job to determine what they really need over mindlessly implementing what they ask for” ring hauntingly in each dev’s ears…)

But I don’t like it, and they wasted all this time coding this. It would have been a lot faster if they had just come to talk w/ me about their idea first. I want what I asked for.

Possibly, but not as much as you think. If they’re in “giving you what you need, not what you ask for” (from their point of view) territory, you’re likely not seeing a finished product. More of a paper mache mock-up to illustrate the idea the developer has for what will solve your problem. And often building the mock-up faster than adequately describing it. (Not to mention it’s a great way for the dev to flush out their own idea.) It’s fully expected if you don’t like it, you can always send it back w/ feedback as to why it’s not what you need. In the long run this saves significantly more time than it costs.

Chapter 5 — Testing All The Things

“The code is done, I’m just testing!” The developer told you. “Great! When will it be deployed?” you ask, confident that surely now if it’s “done” we’ll know an estimated completion date. “I don’t know — we’ll see.” Says the developer. You want to strangle him, I know. It’s a natural feeling.

But “I don’t know — we’ll see”, while unsatisfying, is honest. Testing is more “attempt to break” than anything else. You sit there and try to think of ways to break it, and when you do you fix it. And when you can’t think of anything more to break, (and you’re 98% confident it won’t do harm) you call it “done”. But like the old “spot the differences” games you never really know how much longer you’re going to spend on it until the moment you give up. And every time the you finds something new, the clock restarts.

But eventually they will (if even just because the risk of a bug eventually becomes less costly than the upcoming cost event). And it’ll get marked done, and deployed the following day. CONGRATS, YOU CHANGE IS LIVE!!!


Should I go ask the CTO what’s going on with my issue?

Generally speaking, no. It’s unlikely the CTO will have more knowledge about it than is already on the GitHub page. GitHub can be a bit confusing at times, and your CTO will spend as much time as you wish helping you understand how to interpret it. But your CTO has no interest in being a human

OK, but when should I be asking the CTO / the assigned dev about what’s going on with it?

If there is an upcoming cost event, and there is no activity on an issue, ABSOLUTELY contact the assigned dev. Ask them “are you aware there is an upcoming cost event on date x/y/zzzz?” Hopefully they’ll say “yep”. At that point the conversation should end, as discussing it further only takes time away from completing it. If they say “no, really?!? oh sheet”, say “glad i checked!” and let them get to re-thinking their priorities.

If there is no assignee, then yes, ABSOLUTELY speak to the CTO about it. They’ll likely say “really?!? oh sheet, thanks for the heads up!” and then they’ll start re-thinking the team’s priorities.

I want to see it before it goes live.

Make that request in the issue. The dev should honor it.

You really don’t have any idea how long something is going to take?

We do, after some analysis, have a good idea of the minimum amount of time the coding for an issue will take. But we don’t know how long that analysis will take, nor how many questions we’ll have that’ll need answering, nor how long fixing any code surprises will take, nor how long the testing/breaking phase will take, nor how many times we’ll be pulled onto something higher priority. So while there are parts we can predict, for any singular issue that predicted time is dwarfed by the surrounding uncertainty. So there is little ROI in formally quantifying it or even communicating it with more specificity than “that seems simple” or “holy heck this is going to be rough”.