How I Wrote (most of) a Useful Book This Year

A couple of years ago, I read Write Useful Books by Rob Fitzpatrick. This year I applied it to writing a book about tech debt. These five things had the biggest impact.

1. Imagine the conversation where someone recommends your book

This helped me narrow down my topic from many other ideas I had. I know first-hand that software developers talk about tech debt all of the time. Many of my ideas for chapters were from things I said or thought in those conversations. The ideal conversation is one where engineers are complaining that they can’t get support to pay more tech debt — nearly every chapter addresses that.

2. Make a clear promise

My title is Pay Tech Debt to Go Faster Now because I think the long-term benefits are unsure and over estimated, and there’s a way to get benefits immediately if you direct debt payments at developer productivity to deliver the current roadmap faster (which everyone wants). In that conversation above, my title is the short form of the answer I would give (the book is the long answer)

3. Write in public

I started the book in January and posted it in February. Did a rewrite in March. Posted it in April. That version was discovered by Gergely Orosz of The Pragmatic Engineer newsletter who published an excerpt in September (He also graciously gave honest feedback on what did and did not work)

The article led to hundreds of software engineers signing up to get updates. I just sent them six chapters to read and am getting more useful feedback. I was approached to give a private webinar and shared a different four chapters with them. All of this is honing and shaping the book — the book that I would have written in private would have been very different (and not as good).

4. Market the book by sharing behind the scenes information

For example, this post :)

5. (not in the book): Join an Accountability Group

Rob runs the Useful Books community — https://www.usefulbooks.com/ — I meet with community members three hours per week where we spend 45 minutes of it just writing. A lot of my book got written in those sessions (~70%)

Why LinkedIn Works For Me

With all the talk of migrating to either Bluesky, Mastodon, or Threads, I’m happy that I “migrated” to LinkedIn two years ago.

I joined LinkedIn in 2003, but it was mostly a place to keep my resume for job searching and to message former co-workers.

But, now I use it more like a combination of a social network where I want to stay connected to real-life colleagues and a place to try to get business by networking with potential clients.

My goals with LinkedIn are:

I want to be ambiently aware of which of my ex-colleagues might be looking for jobs and which might be hiring, so I can introduce them to each other. LinkedIn (for whatever flaws it might have) is the best way I have found to do that.
For my business, I want to reach software developers when they are thinking about work and career growth. I want to reach software company tech leaders when they are having problems that I might be able to solve. That happens on LinkedIn and not many other places.

To do those things, LinkedIn has several advantages over other social networks for me:

I see no political content or ads. I checked the box in Settings to turn off political content, and that’s been effective.
LinkedIn shows a normal, time-based (non-algorithmic) feed if you request it in Settings, and it stays that way.
People here seem to be real, not bots. If someone auto-posts their work’s content or is posting a lot that I don’t want to see, I unfollow them, unless I know them well.
Comments on my posts, even by strangers, are civil. Generally, people are positive and casually professional.
My ex-colleagues are here in large numbers, and mostly they talk about work/career things.
There aren’t a lot of posts, and almost every one of them is an update from someone I care about talking about what’s going on in their career. When I read them, I don’t think of myself as doom scrolling — it’s the opposite: it sparks joy to see my friends succeeding.

Twitter was never any of those for me, and so it was easy to give up. It didn’t help me accomplish my goals for using a social network, but worse, it was addictive and a waste of time, so I had to block it. I’m sure Bluesky and Threads are a better Twitter, but I doubt they are a better LinkedIn for how I use it, and as bad as Twitter in all the ways that matter to me.

Writing as Yourself to Yourself

Last April, I was invited to submit a proposal to write an article for Gergely Orosz’s The Pragmatic Engineer. He directed me to write for the newsletter’s audience of software engineering managers and senior engineers at larger companies and to write from my personal experiences. I wrote a proposal and outline, which he accepted, and went on to write a first draft.

I felt very confident that I understood what Gergely wanted and then proceeded to write 7,000 words that he hated. That sounds strong, but he read a few paragraphs and got so frustrated that he stopped and asked me to start over (or give up—but, in a nice way). It took me months to figure out that even though I was writing for myself, I wasn’t writing as myself.

Right after the rejection, I talked to a friend and told her what happened. I told her that that I was anxious about writing in a personal style so publicly—that I would embarrass myself. First, she reminded me that I often try to get points across with stories from my career, and that this was just like that. Then she said: “If you don’t write the book that only you can write, then why do it at all?”

Soon after, I reread “On Writing Well” by William Zinsser. This excerpt cemented what she was telling me (emphasis mine).

Writers are obviously at their most natural when they write in the first person. Writing is an intimate transaction between two people, conducted on paper, and it will go well to the extent that it retains its humanity. Therefore I urge people to write in the first person: to use “I” and “me” and “we” and “us.” They put up a fight.

“Who am I to say what I think?” they ask. “Or what I feel?”

“Who are you not to say what you think?” I tell them. “There’s only one you. Nobody else thinks or feels in exactly the same way.”

“But nobody cares about my opinions,” they say. “It would make me feel conspicuous.”

“They’ll care if you tell them something interesting,” I say, “and tell them in words that come naturally.”

It’s weird, because on this blog, I do write as myself (and my podcast is also my point-of-view on what I am learning about writing). But this blog and my podcast are mostly for self-development. I am trying to transform myself into someone that writes. I hope that my readers learn something, but mostly, this is practice for bigger things.

But, in my article first draft (and in early drafts of my book) I stopped writing as myself. It made it harder to write, and (based on feedback) harder to read. The irony is that I used this blog to practice writing, and almost all of that practice was writing in first-person with my point of view, and then as soon as I tried to write something longer, I abandoned it.

So, I gave in, and it’s gone a lot better. I can still say what I want to say (the tips and practices I think will help people), but wrapping them in stories makes the book easier to understand. Even now, as I am finishing up the book, I can see that my final section isn’t me, and so, I need to rewrite it.

2025 Pre-Planning

In 2024, I applied The Four Disciplines of Execution to my life and business. I detailed the process for my 2024 plan in a blog post for each discipline:

4DX: Applying the First Discipline (pick a goal)
4DX: Applying the Second Discipline (identify and work on the leading indicators)
4DX: Applying the Third Discipline (build a scoreboard to tell you if you are winning)
4DX: Applying the Fourth Discipline (review with accountability)

The first discipline is to pick a single Wildly Important Goal (WIG), but that’s because they imagine that you are doing this only for work. I do it for three completely segregated areas of my life that I can stop from interfering with each other: Work, Personal Growth, and Fitness. I can always make time for each those three independent of the other two. This is important, because the enemy of your WIG (in the book) is the Whirlwind of activities you need to do just to keep going. My work Whirlwind will interfere with my work WIG, but (for me) it doesn’t stop me from working out or working on my personal growth WIGs.

This is just a brain dump of possible WIGs for 2025 in each category.

Personal: I have sold 0 copies of Pay Tech Debt to Go Faster Now (it’s not done), so I want to have it available for sale by end of Q1 2025 and sell 1,000 copies by the end of the year.

Alternatives: (1) Outsource the end tasks of the book and start a new one (2) Sell whatever I can and build a course based on the book that is the focus (3) Sell whatever I can and try to do workshops at tech conferences based on it.

Work: I have a working, but not useful MVP of a new web application, and am mid reconfiguration into a simpler (and somewhat different) mobile web app. I am trying to get to a new MVP by January 2025. My goal is to have paid customers by the end of Q1.

Alternatives: (1) Give up on this idea and try something else (2) Give up and don’t try to make a software product — e.g. turn the book into my business

Fitness: I am in a fitness stasis, which might be what I have to live with for my age. It’s fine. But I still want less than 20% body fat by the end of the year. The way to do it is radical change, which I will think about and perhaps aim for 20% by the end of Q1. The rest of the year will be about maintenance and sustainability. The answer is probably a combination of regular exercise (easy), daily walking (takes time, but could multitask with something), and a more significant calorie deficit accomplished with more careful eating (hardest).

Alternatives: (1) make maintenance the goal and just be happy with my level of fitness (2) make having fun the goal and go for more varied experiences.

This year looks a lot like 2024, but geared more finishing (where 2024 was about starting).

2024 Retrospective

I do my yearly retrospective early because I use it to figure out my plan for the next year. Last year around this time, I thought 2024 would follow the theme of “Heavy Lifting” because I wanted to do more strength training and also take on large projects. But when the year actually started, I had settled on three processes for the year—they were supposed to accomplish bigger goals, and judged on that, I failed on all three. But, the processes resulted in me making progress on each one.

I had thought that I could write two 50-page books this year. Instead, I am almost done with one 130+ page book. I ended up here because my plan was more successful than I thought it would be. In April, I had those 50 pages mostly done and I posted them online for feedback. When I did, it was discovered by Gergely Orosz (The Pragmatic Engineer) who asked me to write an article for his newsletter. It took me four months and a two major drafts (and several rounds of edits) to write an acceptable article. Almost none of this text was in my original 50 pages, so I ended up with about 40 pages more text, some of which was in the article, but more than half was not. Right after that, I was approached to give a webinar to a group of CTOs on technical debt and that led to a whole new section on how Engineering Leadership should think about tech debt.

So, I am here in November with a first draft of my book on tech debt close to done, but in front of me I have several rounds of editing and all of the non-writing work it takes to get a book published. I hope to be done by Q1 next year, and then I’ll be focussed on selling it. My goal is to sell 1,000 copies in 2025.

My fitness goal for 2024 was to lose body fat. I worked out all year, but didn’t really make a dent. I kept trying things (strength training, intermittent fasting, more walking, more cardio, etc), but nothing helped. I kept to a plan all year — I work out 5 or more days a week, eat pretty well, and live a healthy lifestyle, but I might not be ever able to lose this last bit of body fat without radical change. In 2025, I am going to go back to a more cardio-heavy regimen. I was worried about running and my long-term knee health, but I have access to a rowing machine and elliptical, and can do more cardio-based strength workouts with low impact.

My business goal was to launch a web application that I am working on with a partner. We did an MVP (which was the goal), but didn’t get traction with the app as is. However, we did a little pivot in August, which I’m working on it now. I hope to be able to get to another MVP by the end of the year.

The thing that worked well in 2024 was having separate work, personal growth, and fitness goals, but only one in each. I can easily segregate the time between those three areas, but within each of them, trying to do too much would have killed focus, and I might not have made any progress.

Add Date Tests for Daylight Savings

I wrote my iOS App, Habits, after I had been at a job with very strict daylight savings coding rules, so it has lots of unit tests that take the code across the daylight savings/standard time boundaries.

But now it’s been almost 20 years (!) since I worked there, and I’ve gotten bad habits, which bit me last week. On Nov 3rd, at 2am, and for the next week, I had a bug in my code for calculating the date that was “one week ago” because I used JavaScript’s setDate() instead of setUTCDate().

Luckily, my app is still being written, not in production, so it was only a problem in my unit tests. The tests use the current date, and so they inefficiently find daylight savings problems.

The right way is to also have tests that specifically set the date to known daylight savings boundaries and the dates around them.

Technical Debt Typology Research Paper

A few months ago, I got an email from Mark Greville that included a link to a research paper he coauthored, called A Triple Bottom-line Typology of Technical Debt: Supporting Decision-Making in Cross-Functional Teams.

In the paper, the authors identify several categories of tech debt. One category is internal vs. external effects. In my book, I also identified the external category, which I call visibility. The paper thinks of the entire business as the “internal”, but I think of the team itself as the internal part. My separation is driven by difference in communication that the engineering team needs to use for itself vs. the rest of the business. Customers and other public stakeholders would likely be similar to the non-engineering business teams.

Since a lot of my book is about how tech debt affects developer productivity, I break down internal to the various ways it could reduce productivity. I use misalignment to describe tech debt that doesn’t meet the documented standards of the team. When the code is hard to change, for example if there’s messy code all over the codebase (Marbleized Code Fat), I call that resistance. If the code does what it’s supposed to (so no external effects) and the customers highly depend on its behavior, I warn about the risk of regressions.

Another pair they describe is whether the tech debt is taken knowingly or unknowingly. This is useful from a taxonomy perspective and might contribute to tech debt avoidance, but in my book, I write:

I don’t think of tech debt as the result of an intentional shortcut borrowed from the future. Some debt starts that way, but the reality is that lots of tech debt happens because the world changes. Even if your system represents your best ideas of how to solve the problem at hand, your ideas will get better, and the problems will change. You can do everything right and still have bad code, so it doesn’t help to judge the decisions that got us there. Learn from them, but it’s counter-productive to dwell on them.

My chapters on these dimensions focus on using them to decide what to do about the debt, and I don’t think intention is a factor in deciding what to do next.

The paper is worth a look and also has quite a good bibliography if you are interested in research on tech debt. Since the methodology of the research included a literature review, the list of references reviewed is another treasure trove of research.

Adam Tornhill on Tech Debt’s Multiple Dimensions

In the research for my book on technical debt, I ran into this talk by Adam Tornhill:

Adam has a similar perspective to mine: technical debt is multi-faceted, and the right strategy should address its various dimensions.

One of his examples is combining a code complexity metric with data from your source code repository to define low code health hotspots—areas where code is both complex and frequently changed. To find the hotspots, he built a tool to calculate this metric and visualize it. In the video he shows data from big open-source projects (like Android and .NET core) and pinpoints areas that would benefit from work to pay down debt.

Similarly, in my book, I identify eight dimensions of debt. Complexity is something I consider to be part of Resistance, which is how hard or risky it is to change the code. I would also incorporate low test coverage into resistance, as well as subjective criteria. Adam says that complexity is a good estimate of how many tests you need, which is true, and I give you credit for having the tests. I am mostly concerned by complex code that is undertested.

Like Adam, I believe that bad code only matters if you plan to change it. He believes that the repository history of changes is a good indication of future change, which I agree with, but to a lesser degree. In my book, I recommend that you look at the history and shared this git log one-liner as a starting point:

git log --pretty=format: --name-only --since=3.months | sort | uniq -c | sort -rg | head -10

That line will show you the most edited files. To find the most edited folders, I use this

git log --pretty=format: --name-only --since=3.months | sed -e 's/^/\//' -e 's/[^\/]*$//'  | sort|uniq -c|sort -rg|head -10

This data contributes to a dimension I call volatility. It’s meant to be forward looking, so I would mostly base it on your near future roadmap. However, it is probably true that it is correlated with the recent past. In my case, this data is misleading because I just did a reorganization of my code to pull out a shared library to share between the web and mobile versions of my app. But, knowing this, I could modify the time period or perhaps check various time periods to see if there’s some stable pattern.

Generally, my opinions about tech debt and prioritization are very aligned with what’s in this video, especially the multi-faceted approach.

Marbleized Code Fat?

I go back and forth on whether the name “Tech Debt” is the most useful term. In my book, I decided I can’t fight the term, so I use it, but in my opening paragraphs I make an argument that the problem we call tech debt isn’t like other debt.

The most common way I’ve seen tech debt is that it’s just everywhere. It’s not limited to a specific old module, it pervades the codebase like marbleized fat in a good steak, but not as delicious.

Follow-up on my Tech Debt Article in The Pragmatic Engineer Newsletter

About two weeks ago, The Pragmatic Engineer published an early excerpt from a book I’m writing on Tech Debt. This week, he published a follow-up that’s available for free. Read it here:

https://newsletter.pragmaticengineer.com/p/paying-down-tech-debt-further-learnings

If you missed the original article, it’s here:

https://newsletter.pragmaticengineer.com/p/paying-down-tech-debt

After that article came out, there were a few LinkedIn posts with good conversations about tech debt. This one by Ellery Jose has an interesting table that breaks down how to treat technical debt as a financing decision:

https://www.linkedin.com/posts/ejose_tpm-pmo-engineering-activity-7237750795348164610-5mKq/

Also, Guillaume Renoult sent me this post he wrote:

https://medium.com/elmo-software/how-to-sort-out-tech-debt-and-speed-up-development-9a1d27fdd39e

There is a section of my book that has similar ideas to these two posts, particularly team management of debt using evidence and data. I’m hoping to have a draft done of that part in a few weeks. If you want to see an early version, sign up to receive updates.