What is it?

Recently, I have found much success with a simple planning system.

Every season, I jot down a list of goals.

Every week, I jot down a list of things I want to get done that help me accomplish everyday tasks and work towards my seasonal goals.

Every day, I prioritize from items from the weekly list.

Additionally, I have a someday list. A list of projects and goals that I would like to do at some undetermined time in the future.

In software development, tech debt is basically the "someday" list of your codebase.

It is a collection of things that would be ideal to get done but are not prioritized.

Why log it?

Ok, so that's tech debt in a gist, but why should developers bother with tracking it?

Good question.

There are several reasons:

1. If you don't track it, you have to rely solely upon your memory. At some point or another, our memories will fail us.

2. It helps communicate that ideal work is worth doing, even if we're ok with not doing it right this second.

3. It provides assurance that if you can't do the ideal things now that you can still be able to do them later.

4. It helps to generate a longterm vision and goal of a codebase.

How do I log it?

Whatever works. I tend to create a wiki page in the GitHub repository of the codebase.

What do I log exactly?

Again, tech debt is anything that you'd like to do someday.

Frequently, this includes upgrading dependencies, implementing new design patterns, refactoring a decent portion of the code, automating manual tasks, adopting new technologies, etc.

Example

1. Upgrade to Tailwind v3
2. Upgrade to Next v12
3. Create React spring animation hooks
4. Wrap React Query's useQuery hook
5. Move shared, generic components into the design system
6. Adopt a New Way of Organizing the Codebase
7. Reorganize the global state
8. ...etc...

How do I know whether something is a "someday" ideal or a present requirement?

This is the million dollar question. There is no right answer.

I cannot provide a detailed blueprint, but I can provide a couple guiding principles:

1. If the thought of doing it "someday" is stressful, it likely should be done in the present.

2. Do you have time to do it? If not, then you either need to negotiate for time or accept the less-than-ideal situation.

How do I get it prioritized/done?

For some, the concept of a "someday" list doesn't sound all that assuring. There can be memories of previous "someday" items that never see the light of day.

I get that.

While thinking of tech debt as a "someday" list is the easiest way to describe it, perhaps it is more appropriate to think of it as a kanban board of "stretch goals."

"Stretch goals" are things that you prioritize to get done but don't have to get done for you to sleep at night.

Generally, I have found that the best time to prioritize tech debt is around the lifecycle of projects.

Tech debt should be treated as stretch goals added to the main requirements of a project.

If you are a developer on a product team, then you usually have a cadence of 1) planning for a project, 2) starting a project, and 3) wrapping up a project.

As you plan a project, you can prioritize a few interesting tech debt items to be completed thorough the project (although treating them as stretch goals).

Although it's best to treat them as stretch goals, I would recommend padding your estimates for a project with them in mind.

They are not stretch goals because they shouldn't be accounted for in an estimate. Rather, they are stretch goals because they can be the first things be cut in an unexpected event that you need to do less.

In addition to prioritizing tech debt items in the project planning phase, I have also found that a good time to do them is as soon as a project wraps up.

Usually, the end of a project is a slower time where a launched project is being monitored and the next project is getting finalized for planning.

During this slower time, take full advantage to complete tech debt items.

Final Tips

1. Take Initiative

It is nice when a team has a formal expectation/process for completing tech debt items around projects, but take initiative even if such a formal process does not exist. With time, you may be able to advocate for things to be formalized.

2. Tackle tech debt items in separate pull requests.

That way, reviewers can treat it separately from the must-have project pull requests.

3. Keep track of completed tech debt items.

Like with a todo list, I like to see the work that I've accomplished. And, tracking every task that is done can bring a rewarding sense of accomplishment, or it can be an indicator that work needs to be delegated.

Completed tech debt items are also great things to include in your yearly reviews, resumes, etc.

4. Take pride in your craft.

Coding is a craft. Tech debt is a way of improving your craft.

Even though managers may not see (nor ask) about the technical details of your craft, focusing on your craft by making the code ideal will help you stay motivated and relevant for future career opportunities.

But don't get me wrong, people don't need to know the technical details to see the value of someone who is taking their craft seriously and improving a team because of it.

5. Find ways to share your tech debt work with peers.

I'm a big fan of The Developer's Content Model.

In a word, you take the things you are working on and present them to others in unique ways.

You can present your work to a global audience by tweeting things you learned, sharing gists, recording videos, and/or writing blog posts on the work you've done.

When you see people of a global audience take interest in your learnings, it can be very rewarding.

Moreover, it helps you build a portfolio. Even for your current role, you can take tweets and blog posts and repurpose them as documentation for your team.

You can also present your work to a broader audience within your company.

A good way to do this is by either doing a tech talk (gather a group of engineers and present your learnings in a 15-30 minute slide deck presentation) and/or by doing a show-and-tell (gather a group of engineers and have everyone take up to 5-10 minutes to highlight something you learned recently).

Conclusion

I hope you can see that tech debt is much more than tracking "we really should have done this but we couldn't so maybe we'll get to it but probably not" type of items.

Tech debt is a powerful way to improve a codebase, develop your craft, and gain influence and respect among peers.