Category Archives: Writing

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.

Accountability Affinity

Last year, I struggled to find a local author’s group, and realized that it mattered if the others were basically in my genre. The first one I tried was mostly attended by memoir writers. The second, Shut Up & Write, was mostly fiction writers. It was fun to attend, but I didn’t find much common ground, and so I stopped going to them.

Yesterday, I joined the Useful Books community, which is a community of authors that are writing non-fiction books based on ideas in Write Useful Books by Rob Fitzpatrick. He’s in tech, but the community is more broad than that—the genre is described as useful non-fiction: “to create a book so useful that readers can’t help but recommend it.” I went to a virtual writing session yesterday and did end up getting a lot done—and it carried through to the rest of the day.

It’s early on, so I don’t know if this will stick yet, but I do think having something in common with the group helps. Not just that we’re all trying to write, but also the type of thing we’re writing.

4DX: Applying the Second Discipline

The second discipline of The Four Disciplines of Execution is to act on lead measures to accomplish the Wildly Important Goal (WIG). I defined my three WIGs yesterday

  1. Work: no launch blockers in the product by March 31, 2024
  2. Fitness: Go from 23% body fat to under 20% body fat by December 31, 2024.
  3. Personal Growth: Write two 50-page books and put them up for sale by the end of 2024.

For each of those, I have inherently expressed them in a way that defines a “lag” measure. On March 31, I will have launch blockers or not, but there will be nothing I can do on that day to change it. Each day, I will go on my scale and see my body fat %, but I will not really be able to do something that directly affects that in the short term.

4DX asks us to define lead measures that are things we can do right now that will lead to us accomplishing our lag measures. It measures our real-time activity, not the end result of the activity.

For work, it’s going to be time spent coding on launch blockers. I think I can get through the list if I spend 4+ coding hours on launch blockers per week. That might seem like too little—which is common in 4DX goals. You must accept that you still have all of the operational things you have to do. My partner and I are still experimenting, supporting early users, and possibly pivoting. I obviously need to work more than 4 hours per week on the project, but the majority of them are spent dealing with what the business needs today. My WIG is about how we get to the next level.

For fitness, I am accepting that my amount of body fat is very hard to lower (I have lowered it a lot, but have been stuck for a year), and so I am going to work on my amount of muscle mass, which means that I will do more strength training. My lead measure is to do 4 sessions of 10+ minute weight training workouts per week. It’s not 4+, because rest is important. It’s only 10 minutes, because I am working one body part fairly heavy and to failure. I am doing other workouts—these are in addition to what I am already doing, usually on the same day.

To support this, I am adding a secondary leading measure of eating a high-protein, lower carb breakfast 5 days per week. I usually eat oatmeal and fruit, which is perfectly sensible, but perhaps not supporting my WIG as well. I am not a low-carb person (quite the opposite), but I want to reduce this kind of carb. My new staple breakfast will be an egg substitute I make from soaked mung beans (similar to Just Egg) and tofu or tempeh. There is also a cafe near me that makes Just Egg omelets that I will have when I’m lazy. I might also use protein shakes, but rarely.

For my personal goal, since I am aiming for 50 page books, it might be tempting to have a weekly page count goal, but that won’t work for me because I write in drafts. Like my work goal, I think the easiest lead measure will be hours per week, so I will work on the book for at least one hour on five days per week. This will result in 5+ hours per week, but I think it’s important to have a daily practice of writing and not just do 5 hours in one day per week. It seems low, but I have other things I am doing besides this to maintain my level of output. I still want my blog and podcast to be going at the same time. The WIG is about what I can do to get to another level, not something I do instead of what I am doing now. In 6 months, that’s about 130 hours, which should be enough time to write and edit 50 pages.

You might disagree with my goals, and how I am trying to accomplish them. That’s ok, but that’s not the point. The point is that I am trying to accomplish big goals by concentrating on a process that is much more short-term and something I can definitely do (4DX calls this playing a winnable game). I will be checking in every 13 weeks to see if I am moving the lag measure, and adjust if not.

My Current (2024) Blog Stack

This blog is 20 years old. I started with static files generated from CityDesk and hosted on a simple server. Then, I went to static files generated from RapidWeaver on Mac. In 2012, I realized that I needed it to be easier to post, so I migrated to WordPress.

I very rarely updated this site in 2012. I finally decided to bite the bullet and get everything into WordPress so that I could update from any machine, not just the one I had RapidWeaver installed on. I immediately got a bunch of benefits (1) the site has a mobile theme (2) I can update from my phone or iPad using WordPress apps (3) dealing with images and other media is a lot easier and (4) publishing is automatic and fast. Since the migration, I have maintained about a weekly update schedule.

I have been on WordPress since then and can’t see any reason to change. A few years ago, I migrated to DreamHost, which I recommend for WordPress hosting. They can do more than WordPress—I also host App-o-Mat there (which is a custom Django site).

My theme is WordPress’s Twenty Twelve. Each year they make a new theme (named for the year). It was the default when I migrated, and I didn’t look for anything else because I wanted something plain, which it is.

I really try to limit my plugins. There are three that I recommend if you need the features they implement.

I use the Blubrry plugin to help me self-host my podcast. It generates the podcast feed automatically from blog posts.

I use the Contextual Related Posts plugin to put related links at the bottom of each post and the Exclude Pages from Navigation plugin to let me control which pages show up in the navigation.

Aside from those, I just picked the most popular ones for generating a sitemap and to make it easier to embed videos hosted on YouTube and Vimeo.

I use Hover as my domain name registrar.

I have no plans to change anything. I do keep an eye on the CMS sites that offer some distribution (Medium, Substack, etc), but I care too much about owning my URLs and keeping content in something I could easily migrate away from.

It was 20 years ago today…

I started this blog on December 23, 2003 with this post about automating software processes. I had just decided to leave my job in the new year and start consulting, so I thought it would be a good idea to have a website with a blog, so I made a simple one. I don’t even remember what software I used. Soon after, I ported it to Fogcreek’s CityDesk.

At some point I decided to use a Mac full-time, so I ported the site to RapidWeaver. And then like many others, I ended up on WordPress, which I still use. I have a giant redirect file that keeps the URLs from CityDesk and RapidWeaver working.

I’ve written about the impact that this blog has had on my life and career before, so I’ll just leave some links and not repeat myself