< back to all resources
Resources
my engineers keep telling me not enough is figured out
How much detail should go in the spec? How much should be figured out before starting dev work? My engineers keep telling me not enough is figured out, so they can't start working on my thing. HALP ME ERIN.
—Krampus
Dear Krampus,
Ahh, this is such a great question, and one that may require several posts to cover. Nevertheless, let me give this a try.
Rage against the spec
I really, honestly, dislike the term and even the concept of a “spec” so much. Typically a spec is structured as a document written entirely by the product manager that lays out all of the product “requirements” for the rest of the team to follow. It walks the engineers through exactly what and how the product should work, and leaves only the implementation details up to the engineering team.
This is a really, really dated concept. It much more closely resembles the typical IT partner process that happens in large companies. I know this because I was that person for 6.5 years. Now, it’s entirely possible IT project management has changed in the 8 years since I left it, but nevertheless is a really helpful comparison for me.
System of a spec
In the spec universe, we ask our customers or business partners what they need. We determine everything that they will need in the foreseeable future, and we write those requirements into a multi-page document. We write out test cases that should cover every possible permutation of actions a user could take. We get THE ONE design to rule them all. And then we hand it over to engineering and ask them how long it’s going to take.
This is what we like to call “waterfall” development. Waterfall has its place—for example, if you’re building aircraft engines, it’s probably for the best that you have long-term plans—but that place is not in a small or midsize software company.
Alternative systems
In the problem universe, we ask our customers what they need. Then we ask them why they need it, and what they’re actually trying to accomplish. We throw out the thing they asked for and instead concentrate on the outcome they desire. We write out those problems and relevant constraints, and we only look at the most important ones. We collaborate with a team of designers and engineers to dream up the best possible solutions to those problems, and we then write those solutions up as user stories.
This is targeted, collaborative, and modular. If something changes, rather than updating a long out-dated document and determining how the change cascades through all of our hard-laid plans, we simply delete one story, and replace it. We simply de-prioritize one story, and move two others above.
The connotation of spec
There are additional reasons to avoid the use of even the word “spec.” Some may call this semantics, but in a world where we are leading and influencing a group of smart, opinionated engineers to pursue a vision, semantics matter. So much of leadership comes down to understanding the nuances is which words you use, and how you use them.
The word spec means, quite literally, specifications. Requirements. Things that should be followed exactly. If you build something to spec, you build something that exactly matches the requirements. There’s typically not a whole lot of creativity involved, or room to come up with something that’s better than the spec.
Master of solutions
If your engineers are telling you not enough is figured out and you don’t know what needs to be figured out, I’d suggest booking a room for half a day and hashing it out with them. There is definitely an amount of product ideation, story-writing, and technical exploration needed before diving in, and that needs to happen at the team level. The team doesn’t need you to flesh it out yourself, but they might need you to lead them through the process of figuring that out.
Here are some questions to ask yourself:
Does your team fully understand the problems they’re setting out to solve?
Have you and your team already drawn up a rough agreed upon solution?
Has your designer contributed lo-fi designs that support that solution?
Has your team walked through proposed business logic and identified edge cases?
Does your team have enough of an idea of the solution to:
Research required technologies?
Design the database?
Design the APIs?
Articulate what could be delivered in a phase one?
There’s a good chance that if they’re stuck, you probably haven’t spent enough time with the team addressing these questions. Remember, you don’t have to come up with the solution or edge cases or anything else on your own. But you do have to facilitate the process.
You’re gonna go far, PM
Remember the tools of our trade, and you’re going to be just fine.
Make sure your tripod is set up
Get to the heart of the problem & create a problem page
Have a sketch session with your team to collaborate on a solution
Have follow-up sessions to flesh out core product logic
Write great stories
You’ve got this, Krampus.
Erin
paying off tech debt -OR- my PM is scary
Let’s tackle the question: “I’m an engineer, and I am told to work on “paying off tech debt”, but I think if I do that it’s going to make my product manager mad. @eboyle what do I do?”
I’m an engineer, and I am told to work on “paying off tech debt”, but I think if I do that it’s going to make my product manager mad. @eboyle what do I do?
Dear Engineer,
My advice is to get a new PM. Nah, just kidding. (A little. Mostly. Kind of.)
Questions like these are hard, because they’re not directly within your control. I do believe—quite strongly—that no product manager worth their salt will ever flat-out reject talking about the work you need to do to clean up tech debt. A good product manager will ask questions, and work with you (or your engineering manager) to determine how to layer tech debt work into ongoing product work.
Weighing the options
Here are some questions I would ask as a PM:
What’s the scope of tech debt you plan to address?
How urgent is this debt? If we don’t do something, will we have problems in 2 weeks? 2 months? A year?
Does this tech debt directly impact any of the product areas we have plans to touch?
How does this stack against other tech debt within our domain?
How might this impact our existing goals? Will we not be able to address [problem y] if we pay down [tech debt x]?
Can we divide this work up into smaller chunks?
Now, note that I don’t ask any of these questions because I don’t think paying down tech debt in important. But rather, I think it’s just as important as product feature work, and prioritizing feature work goes through a similar gauntlet of questions. The main difference is that you, the engineer, know way more about this problem set than me, the PM. So be a little patient and get me up to speed.
At this point, it really becomes a joint decision between the engineering and product managers. Both are responsible for weighing the trade-offs and coming to a reasonable compromise.
Build tech debt pay-down into your team processes
Every product or product area is unique when it comes to how much time needs to be spent working on features, updating designs ( design debt is real, y’all), or paying down tech debt. A healthy product tripod (engineering manager + product manager + lead designer) should decide on the default weight of tech debt for their ownership area.
For example, if your product is fairly healthy and has a steady (but not overly aggressive) feature release cycle, a good rule of thumb is to dedicate 20% of engineering resources to paying down tech debt. This might mean that you always have one or two engineers working on tech debt in a rotation, or it might mean everyone is responsible for spending two days a sprint paying down tech debt.
A product area that isn’t seeing a lot of new product development, on the other hand, may have a higher rate of tech debt management. A feature in startup growth mode? Probably not going to be working on much tech debt.
Ok but I have a leaning tower of Pisa-code
Are things… leaning? Does it feel like you’re playing a very technical game of Jenga? Are you worried that working on the next feature will start crumbling the whole damned thing? Cool, 20% is probably not going to work for you. This is a perfect time for the tripod to reassess priorities and put the majority of focus on paying down the debt before it becomes a 4-alarm fire.
Please don’t let it become a 4-alarm fire. Don’t let your PM let it become a 4-alarm fire. But also be careful of how many times you play that card. If you treat everything as urgent, there’s a good chance you’ll start losing credibility with the PM. If it can honestly wait a year, say that. If it could really use an overhaul but really only this one piece needs to be done soon, say that. If it’s going to hell in a hand basket, for heaven’s sake say that too.
What even is tech debt?
Spoiler: almost everything in this post are questions I ask when I’m interviewing engineering manager candidates. I worry less about the answers, and more about how much thought has gone into tech debt as a concept, how much experience has gone into processes, and whether those views are nuanced. Let’s be honest, this is all just a pile of nuance.
So, here’s my take on what counts as tech debt. But again… nuance. Hand wavey. Also some things may fit into more than one of these categories.
Backend performance issues (think: long-running queries, database design issues, capacity issues)
Frontend performance issues (think: insanely large images, network chattiness, non-incremental loading)
Spaghetti code (we didn’t know where this was going to go when we first built it, but now we do and this is only going to get worse)
“Building feature xyz will take us 10 years and a million bribes in the form of cookies if we don’t redo this” things
“I-don’t-understand-but-trust-that-you-do” things
“Starting to address this now will prepare us for that thing we wanna do next year” things
Bugs. Yes. It’s true. Bugs happen. WE WILL SMASH THEM. But this is not, in the classic sense, tech debt.
You, too, can own a backlog
In my (in)famous guide to writing stories, I decree the following:
Thou shalt have all stories, chores, and bugs related to a product initiative in a single backlog
Exception: Tech debt or tech-only projects may have a separate technical backlog
This is probably a great time to talk about that exception. I strongly advocate for having a backlog dedicated to non-user-facing-bug tech debt. There’s already enough ordered chaos in the main backlog—there’s really no need to complicated matters further by adding in tech debt stories that I (or your product manager) may or may not understand—and I say this as a fairly technical PM.
There are several key advantages to having a separate tech debt backlog, other than saving my eyeballs from confusing stories:
The engineers can manage this backlog independent from product and design
Having a single list of tech debt allows the engineering manager and engineering team to prioritize tech debt amongst other tech debt
Whether everyone spends a percentage of the sprint working on tech debt, or whether there’s a rotating spot on the team, everyone has a single prioritized place to know what to work on next
Having actual stories can help keep engineers on task / prevent y’all from going down a rabbit hole of code optimization that I know you all fantasize about. I know you. Do not doubt me.
Having actual stories means engineers can pull them into a sprint, so that there’s no magical work happening that’s not being tracked against your velocity
But Erin, I thought tech debt should not be a thing that’s estimated!
Did I say that? I actually don’t think I said that, although… maybe I should’ve.
Honestly, whether to point or not to point tech debt, that is the question for your whole scrum team. Many teams decide to not point tech debt. Some teams decide to point-only-as-an-effort-box tech debt stories. It kind of doesn’t matter to me. As long as you pick one method and stick with it, it all can work.
No matter the method and whether there are points on tech debt stories, dragging them into your sprint will help your PM understand what you’re working on and where your time is going.
NOT BECAUSE THEY WANT TO MICRO-MANAGE YOU.
Seriously we have enough to do. We have no interest in micro-managing you. But we often have to set expectations and communicate progress to stakeholders and partners within the company. The more we can do that without having to bug you about what you’re doing, the happier we both are.
It’s ok to make your PM a little mad. Sometimes.
A product-engineering team is a lot like a system of checks and balances. It can feel like PMs are the executive, legislative, and judicial branches all in one, but it’s not actually true. Healthy teams should have disagreements. That doesn’t mean you don’t treat each other with respect… you absolutely treat each other as humans. And you also should push each other. Our strength as a team comes from being able to challenge one another because we all have different backgrounds, strengths, and perspectives.
when it comes to Product managers being mad… it’s all relative.
tl;dr
So, that’s what I’d do. Make sure that you, as a team, talk about how to handle ongoing tech debt pay-down vs one-off or project-level pay-down. Be prepared to answer your PM’s questions about what you’re proposing. Prioritize tech debt within a backlog. And, you know… irritate your PM once in awhile. Tell them I gave you permission.
Until next time,
eboyle