Category Archives: Writing

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.

Making Time

You can say that you find time to do something or take time to do something, but I like saying I make time to do something.

Time, of course, can’t be made, so it’s magic if you do it.

Passive Voice Commit Messages

I saw a suggestion to use Subject-First Commit Messages to make it easier to scan the log. I switched over to this about two weeks ago and like it.

When you write commit messages this way, they tend to result in passive voice sentences like “Project cleared from project prompt dialog when closed” and “Title added to date prompts”. Many style books suggest that you not use the passive voice, which is then repeated as a rule. But, the passive voice is useful, and is often used by the best writers (go check your favorite). Even those style books (like Strunk and White) give exceptions.

When writing a sentence, it’s important to control the subject. In most commit messages, the implicit subject is the programmer. For example, in “Added title to date prompts”, the subject “I” is dropped. Since we know that the programmer is making the commits, we don’t need to constantly repeat it. It’s better to pick the most important noun in the sentence and make that the subject, and to do that (in English) you have to use the passive voice.

I talked about this in Write While True Episode 37: The Passive Voice Was Used. If you want to see a thorough take-down of anti-Passive Voice zealots, watch Larry McEnerney analyses the Gettysburg Address, which I discuss in the podcast episode.