This post is a collection of notes on writing Crafting Engineering Strategy, how I decided to publish it, ways that I did and did not use foundational models in writing it, and so on. (View Highlight)
One of my decade goals for the 2020s, last updated in my 2024 year in review, is to write three books on some aspect of engineering. I published An Elegant Puzzle in 2019, so that one doesn’t count, but have two other books published in the 2020s: Staff Engineer in 2021, and The Engineering Executive’s Primer in 2024. So I knew I needed one more to complete this decade goal. At one point, I was planning on finishing Infrastructure Engineering as my fourth book, but honestly I’ve lost traction on that topic a bit over the past few years. (View Highlight)
Instead, the thing I’d been thinking about a lot instead was engineering strategy. I’ve written chapters on this topic in my last two books, and each of those chapter was tortured by the sheer volume of things I wanted to write. By the end of 2024, I’d done enough strategy work myself that I was pretty confident I could take the best ideas from Staff Engineer–anchoring the essays in amazing stories–and the topic I’d spent so much time on over the past there years, and turn it into a pretty good book. (View Highlight)
It’s also a topic that, like Staff Engineer in 2020 when I started writing it, was missing an anchor book pulling the ideas together for discussion. There are so many great books about strategy out there. There are some great books on engineering strategy, but few of them are widely read. My aspiration in writing this book was to potentially write that anchor book. It’ll take a decade or two to determine whether or not I’ve succeeded. At the minimum I think this book will either become that anchor or annoy someone enough that they write a better anchor instead. Either way, I’ll mark it as a win for advancing the industry’s discussion a bit. (View Highlight)
While I was writing this book, I was also increasingly using foundational models at work. Then I was using them to write tools for managing this book. Over time, I became increasingly fascinated with the idea of having a version of this book optimized for usage with large language models. (View Highlight)
For this book in particular, the idea that you could collaborate with it on creating your own engineering strategy was a very appealing idea. I’m excited that this ultimately translated into an LLM-optimized edition that you can also purchase on Amazon, or you can read the AI companion’s text on craftingengineeringstrategy.com, although you’ll have to buy the actual book to get the foundational model optimized file itself (e.g. a markdown version of the book that plays well with foundational models). (View Highlight)
This is the culmination of my thinking about the advantage of authors in the age of LLMs, where I see a path to book turning into things that are both read and also collaborated with.
Regarding the foundational model optimized-version, at its core, this is just running repomix against the repository of Markdown files, but there are a number of interesting optimizations for a better product. For example, it’s adding absolute paths to every referenced file and link, including adding a link to each chapter at its beginning to help models detect to them as references. (View Highlight)
It’s also translating images into text descriptions. For example, here’s an image from one of the chapters.
Original image of a systems model (View Highlight)
Then here is the representation after I wrote a script to pull out every image and replace it with a description.
(View Highlight)
My guess is that many books are going to move in the direction of having an LLM-optimized edition, and I’m quite excited to see where this goes. I’ll likely work on an LLM-optimized edition of Staff Engineer at some point in the near-ish future as well. (View Highlight)
When non-authors talk about LLMs making it easier to write books, they often think about LLMs literally writing books. As a fairly experienced author, I have absolutely no interest in an LLM writing any part of my book. If I don’t bring something unique to the book, the sort of thing that an LLM would not bring, then generally either it isn’t a book worth writing or I am the wrong author to write it. As a result, I wrote every word in this book. I didn’t use LLMs to expand bullets into paragraphs. I didn’t use LLMs to outline or assemble topics. I didn’t use LLMs to find examples to substantiate my approach. Again, this is what I know how to do fairly well at this point. (View Highlight)
However, there are many things that I’m not that good at, where I relied heavily on an LLM. In particular, I used LLMs to copy-edit for typos, grammatical errors and hard-to-read sentences. I also used LLMs to write several scripts that I used in writing this book:
grammar.py which sent one or more chapters to an LLM for grammatical and spelling correction, returning the identified errors as regular expressions that I could individually accept or reject
import.py which translated from my blog post version of the posts into the craftingengstrategy.com optimized version
links.py which I used for standardizing format of chapter references, and balancing the frequency that strategies were referenced
For Staff Engineer, I put up staffeng.com. For The Engineering Executive’s Primer I just posted things on this blog, without making a dedicated, standalone site. For Crafting Engineering Strategy, I decided to put together a dedicated site again, which maybe deserves an explanation. (View Highlight)
My writing over the past few years is anchored in my goal of advancing the industry, and I think that having a well-structured, referencable version of the book online is a valuable part of that. If people want to recommend someone read Staff Engineer, they can simply point them to staffeng.com, and they can read the whole book. They might also buy it, which is great, but it’s fine if they don’t. The Engineering Executive’s Primer is just much less referencable online, so someone ultimately has to decide to buy it before testing the content, which undermines its ability to advance the industry. (View Highlight)
At this point, my experience is that most books benefit from having a dedicated site, and that it doesn’t detract from sales numbers. Rather, if properly done with clear calls to action on the site, it supports sales very effectively. (View Highlight)
I worked with O’Reilly to publish this book, same as I did for my previous book, The Engineering Executive’s Primer. My continued experience is that it’s harder to create a book with a publisher, the financial outcomes are significantly muted, but the book itself is almost always a much better book than you would have created on your own. (View Highlight)
Original image of a systems model (View Highlight)
(View Highlight)