Category Archives: Writing

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%)

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.

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.

LLMs Can’t Turn You Into a Writer

In Art & Fear, the authors write:

To all viewers but yourself, what matters is the product, the finished artwork. To you and you alone, what matters is the process, the experience of shaping that artwork. The viewers’ concerns are not your concerns. Their job is whatever it is, to be moved by art, to be entertained by it, whatever.

Your job is to learn to work on your work.

If you use LLMs to write for you, you will end up with writing. You’ll pass your class, get by at work, or get some likes on a post. But you will not become a better writer.

It might even be hard to become a better judge of writing. If you do, it won’t be by reading what LLMs bleat out. It won’t be by reading their summaries of great work. “Your job is to learn to work on your work” and to do that you need to do your own writing and limit your reading to those that do the same.

Identity is a Powerful Habit Totem

In my post, Environment Hacking, I wrote about a problem I ran into with BJ Fogg’s Behavior Model:

One of BJ Fogg’s insights is that you already have habits that are completely automatic, so he suggests using those as prompts for a new habit you are trying to build. You repeat to yourself, “After I do [some automatic habit], I will do [some tiny version of a new habit]”. For example, “after I brush my teeth, I will floss one tooth”. In this case, the environment is your existing habit.

This works great, but I have some habits that I can’t easily tie to existing one (or at least I haven’t been successful at it yet). For these kinds of habits, I have been thinking of “habit totems” I can put into the environment to prompt me.

In that article, the idea was to place objects in the world that remind you to do things when you see them. I called those objects “Habit Totems”. A Habit Totem works because it’s always present at the place where you want to do the habit, and it prompts you to do it.

Your identity can be a powerful Habit Totem because it is always present, and it changes how you perceive the environment such that it turns everything into a prompt.

I have an identity as a programmer. I program all of the time without prompts, because everything reminds me about programming. I also have an identity as someone that eats plant-based food—no prompt needed at the grocery store or restaurant because it’s just a part of who I am.

But I struggle with my aspirational identities. I want to be a writer, but I still haven’t assumed that identity enough for it to be a driver on its own. I want to make my plant-based identity more specific by becoming “whole-food plant-based”, but I haven’t made a lot of progress.

What I am trying now is to try to internalize that I have already become the identity I aspire to be. I walked through the grocery store last weekend just repeating “I only eat whole plant-based food” and managed to leave with a cart more aligned to that identity. I am writing this blog because “I am a writer” and a writer writes. When I thought about my experience at the grocery store, I was more compelled to write about it.

It’s only been a few days, but it feels very powerful so far.

Static Site Generation from Django

I created App-o-Mat in 2014 using Django (pre-1.0) and Python 2, and for all that time it was deployed on relatively cheap hosting that supported Python backends. Unfortunately, my host recently decided to stop supporting Passenger and Django had long ago abandoned fastcgi. My options were to upgrade my hosting or look for an alternative host.

I had been wanting to look at AWS’s App Runner service, so I started reading through the docs and doing a trial port of my site. Since I also use MySQL, I had to also learn RDS. At some point I knew enough to try to figure out what this was going to cost to host and it turned out to be more expensive than just upgrading my hosting platform, so I abandoned AWS.

App-o-Mat is a content-driven Django app. It doesn’t have any interactivity in the public pages—most of the advantage of Django to me is in its CMS admin interface where I can author new articles. The public site is essentially static.

So, rather than upgrade my host, I decided that I now just run the site locally on my laptop and use wget to crawl it to get a static site that I scp to my host. I had to manually cause issues to get my 404 and other error pages to be part of the crawl. I see that there’s a project, https://django-distill.com, that purports to turn any Django project into a static site generator, but it also doesn’t automatically handle your error pages.

I might use django-distill in the future, but I write new content very infrequently, so we’ll see.

Help my book

I am writing a book titled Paying off Tech Debt When You’re Not In Charge.

The intended audience is software engineers working within orgs where they are having trouble getting tech debt paid.

If this sounds like a problem you have and would like to read my first three chapters, let me know. I am in very early stages and want to make a useful book, so the best feedback would be if it was useful to you or not.

Useful Books I Admire

I am trying to write a useful book on technical debt. I am near the beginning of the process and still trying to find the format. To do that, I’ve been thinking about useful books I have read and what I loved about them.

The first one that came to mind is Writing Down the Bones by Natalie Goldberg. It’s part memoir and part writing exercise workbook. It’s similar to the Artist’s Way by Julia Cameron, but the tone resonated more with me. Bird by Bird by Anne Lamott would also fit this category. These are books you are meant to apply immediately.

I’ve been writing a lot about The Four Disciplines of Execution lately. This book’s style is just a very straight-forward business how-to with case studies. For me the technique is so compelling, that the format almost wouldn’t matter. It’s a four-step process with four-steps clearly described.

All of Rob Fitzpatrick’s books are great, but The Workshop Survival Guide is particularly useful. The authors assume that you have a workshop coming up and are in a hurry. They don’t waste time and get right to helping you design it.My favorite part is the structures for workshops of various lengths. Best tip is to use Q&A to make the timeline springy. Makes me want to give a workshop.

Looking at my post on Great Software Writing (that influenced me personally), eXtreme Programming is the one that strikes me as the most useful. This book introduced me to CI, unit-testing, pair programming, and refactoring. I use the lessons from this book daily.

Write for Yesterday

I aspire to write a post every day, but sometimes I’m busy and I forget. I don’t want to break the streak, so I allow myself to post to yesterday, which I’m doing today.

Short-Form Style

There’s a style of writing you see a lot on LinkedIn Posts. It’s meant to be easy to consume.

It works well there because it meets the user where they are—in a hurry.

But, it doesn’t work for a whole book.

Short form media is great to bring attention to a topic with humor or emotion, but we read books because we want more than that. You are ready to go deeper. The only way for an author to communicate that depth is to create interesting, cohesive paragraphs that have a range of sentence types and clauses because deep content is nuanced and you need the clauses to understand it. The paragraphs need to be longer than than a sentence. The sentence length needs to vary.

Or else every sentence will sound equally important.

Or equally unimportant.

And it’s exhausting to read.

Note: The third season of my podcast was all about sentences and paragraphs. Episode 28: Complex Sentences and Episode 29: Loose Sentences are particularly related to what I am getting at here.