I collect and prioritize tech debt for a living

Amara Graham - Dec 15 '21 - - Dev Community

This is not a joke.

In fact, one day I hope we get to a point where I work myself out of a job - where developer experience (DX) is so baked into the development or product lifecycle that I don't have to have a whole separate team/function/program devoted to making sure developers have what they need to be successful in the most efficient manner possible.

But today, at most companies, that is just not the case.

Tech debt is a natural occurrence. It's unavoidable for non-trivial projects. Not everything can be the highest priority. Not everything can be done immediately. You will inevitably hit a point in your company or project where something will hit the backlog, the backlog will grow, and you'll need to address it. Maybe not now. Maybe not soon. Maybe not... ever. 😱

The product managers, aka PMs, (in collaboration with engineering and engineering managers) do a great job of assessing feature requests, maintenance tasks, and new functionality, but likely from the end-user perspective, which may not always be developers. They may also have competing priorities like helping close $$$ deals with specific feature requests and prioritizing foundational enablement work, which could be considered tech debt itself.

I get to lazer focus on the developers perspective - do developers have what they need to be successful today with the features and functionality available today (not tomorrow!) and if not, what do we need to make the biggest impact in a timely manner, acknowledging that timely manner may not be the instant gratification most folks are looking for today. 🙃

But I digress.

I have amassed a huge collection of things ranging from stuff that people thought they would fix and never did, to things that no one ever thought about and now I have no less than 100 people scream-panicking about why this hasn't been done. Also included in this collection is the skeletons like "oh we hardcoded someone's personal account a decade ago and it still mostly works so we left it" to "this was an internal hackathon project and no one really maintains it, but a former PM guaranteed it to a customer 2 years ago". STOP. DO NOT PASS GO. DO NOT COLLECT $200.

I've been uncovering and collecting things like this since I started in DevRel, whether I had a DX title or not. It's no one's fault and its not a valuable exercise to point fingers and understand why or how we got to this point, but it is critical to get these surfaced and prioritized.

To provide a more specific example, think of API reference docs. The (expected) (anticipated) standard is to make them available in something that is based on OpenAPI spec. Swagger or Swagger-like tools come to mind. It's an experience that provides developers with all the info they need in a way that's standardized.

This doesn't mean you can't provide API reference documentation in a way that doesn't provide developers everything they need and isn't Swagger-esque. It just means that you may increase the cognitive load on the consuming developer as they work to understand how you've structured your API reference docs.

This may seem trivial until you realize developers may be working with many API references across many companies and vendors to get their one solution to work. Taking just a little extra time to provide an expected or anticipated experience with your API reference could mean the difference between a frictionless onboarding and execution, and one where the developer has to fight your docs and your product to use it.

This is just one example, and one example does not a collector make. But I'll give you one more, also in the API space.

My favorite tech debt that doesn't seem like tech debt is making a GraphQL API available with your product.

This is still largely bleeding-edge technology and requires educating developers on transitioning their skills, often from REST. Getting the true value from GraphQL is often much easier to see when you design and implement the GraphQL schema yourself, not when you are trying to consume it, and certainly not when you are trying to consume it like a REST API.

Making your GraphQL API available for consumption doesn't provide an efficient experience for the devs who have never used one. You'll need to include additional educational resources and links to uplift their skills. If you don't make recommendations, they'll find this content on their own and you risk them never coming back.

Until working with graphs becomes the defacto API, set your expectations at meeting developers where they are which largely means coming at APIs from the perspective of REST.

And don't forget that SOAP and gRPC exist too.

Anyway, just felt like I needed to get that rant update to my job description out there on the internet. I'm sure it's relatable. At least lie to me and tell me it is.


I apologize for doing books a disservice by using them in my cover image. I searched Unsplash for "collector", "collection", and "hoard" only to get nothing I really thought worked.

Photo by Eli Francis on Unsplash

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .