Software Engineer's Library
Highly recommended essays, books, conference talks, and more for software engineers striving to build better products.
#Software Design
The First Chapter of "An Introduction to Object-Oriented Programming"
book
Read the whole first chapter—free at the author's website—and pay special attention to section 1.4. That spot in the book is when finally saw OOP as a community of collaborating objects that model the interactions and responsibilities we observe in agents of purpose in the real world.
UI and Capability
essay
While ostensibly about UI design, this essay was instrumental for me in developing a better mental model for identifying the meaningful concerns in a system. "The more you see how each piece of design and code supports a specific capability, the easier it is to find order in the chaos of product development."
Colocation
essay
When one thing has to change because another thing changed, put them as close as possible together.
High Cohesion, Loose Coupling
essay
A famous yet often misunderstood description of systems that are easy to change.
A Daily Practice of Empirical Software Design
video
"The cost of software is approximately equal to the coupling. And that's what's being addressed with software design. The reason we design software is so that we can change it... and change it at reasonable cost."
Separation of Concerns is Fundamental to Building High-Quality Software
essay
It's impossible to understand everything at once, and understanding something is important if you're going to change it.
CSS Utility Classes and "Separation of Concerns"
essay
It's an exceedingly rare experience, but I had an actual epiphany the first time I read this. My mental model for software design was changed forever.
CRUD is an antipattern
essay
Is the business valuable because it's just shuffling data back and forth?
Active Record: How We Got Persistence Perfectly Wrong
essay
The cleverness of Active Record introduces complexity to your system that can only be mitigated, never resolved. Be careful not to fall in love with your mitigation techniques.
The Five-Step Engineering Process
video
Do them all and take the steps in order. Step 1 is often overlooked because everyone assumes someone else already did it, but it's everyone's job. (Starts with the link at about 13:13 and ends at 28:23.)
Systemizing Kick-Off
guide
Experienced engineers approach a new project by starting with the riskiest bits instead of solving the easy puzzles first. This guide shows you how it's done.
Unfolding the Interrelationship Diagram
guide
What do you do when there are too many problems to solve and you don't know which one to tackle first? Map out the parts that depend on each other and pick one that unlocks the rest. (The author posted a helpful follow-up on how to resolve the tension when dependencies and riskiest unknowns don't give you the same starting point.)
On Pair Programming
guide
A detailed guide on how to go about pair programming — especially helpful for those who have never tried it before. It also covers challenges that devs typically face and responds to common criticisms of the practice.
How to Conduct Effective Code Reviews
guide
If you've never quite felt comfortable performing a code review, or if your suggestions don't seem to have the intended effect, this guide provides a lot of great recommendations to chew on.
The Twelve-Factor App
guide
Principles for constructing SaaS apps that are easy to test, deploy, and scale on modern cloud infrastructure.
Migrating a production database without any downtime
guide
How to safely change a production database without putting the app in maintenance mode. Especially important for containerized apps.
Squeeze the hell out of the system you have
essay
"Always put off significant complexity increases as long as possible."
Avoiding mid-air collisions with ETag
guide
At a certain scale, there's always the chance that multiple people will try updating the same version of a resource on the server. Before jumping to clever frontend notifications to let users know there's been an update, put this in place to prevent collision in the first place.
Server-Side Rendering is a Thiel Truth
essay
A lot of people aren't going to like this, but it's true. Most web apps just don't benefit from the complexity and engineering overhead of modern frontend frameworks like React.
Don’t Build A General Purpose API To Power Your Own Front End
essay
When you have a backend API that feeds a frontend you also control, those aren't separate concerns. They're two sides of the same app. You need to be able to make changes and optimize for your performance needs without worrying about third-party API consumers.
Should we rebrand REST?
essay
It became a buzzword in tech almost immediately, but REST in theory couldn't be further from REST in practice. All the JSON-based HTTP APIs marketing themselves as REST APIs aren't, actually. So maybe it's time for some new terminology?
Best practices for REST API design
guide
This guide provides lots of helpful guidelines for HTTP APIs, though I'd say GitHub has a better pattern for API versioning.
Why htmx Does Not Have a Build Step
▴back to topessay
Design is all about the right decisions made for a given context. If you publish a JavaScript library that you intend to work in the present and decades into the future without any updates, what unorthodox decisions would you make?
#Teams
The "Brent" Effect
essay
Brent is your go-to. He's critical. The company wouldn't be able to function without him! You see where this is going, don't you?
Team Topologies
book
The authors present four different kinds of teams as the basic blueprint, with most teams being the kind that is long-running, crossfunctional, and organized around delivering a particular business outcome.
Accelerate
book
One of my top recommendations for anyone putting software into production or leading the people who do. Chock full of high-quality research on how to deliver valuable features quickly in a software environment without chaos.
On Pair Programming
guide
A detailed guide on how to go about pair programming — especially helpful for those who have never tried it before. It also covers challenges that devs typically face and responds to common criticisms of the practice.
How to Conduct Effective Code Reviews
guide
If you've never quite felt comfortable performing a code review, or if your suggestions don't seem to have the intended effect, this guide provides a lot of great recommendations to chew on.
Diátaxis
guide
A helpful framework for writing technical documentation. It presents four different types of docs and emphasizes writing for the audience of each type specifically, avoiding the confusion that often follows from blending them together.
Thread on designing a happy and healthy remote work environment
▴back to toptweet
Some simple but effective ideas for a better remote work experience.
#Career
How Developers Stop Learning: Rise of the Expert Beginner
essay
Find ways to gain knowledge and experience outside your bubble so you don't fall prey to thinking you've figured it all out just because you're the smartest one in the room.
What I Wish I Knew About Onboarding Effectively
essay
A great mindset for your first few months on the job.
Riding the Writing Wave
essay
"The ultimate test of how well you understand something is how clearly you can explain it in writing — clear writers are clear thinkers. As a wise man once said: 'everything is vague to a degree you do not realize until you have tried to make it precise.'"
Make Your Point and Get Out of the Way
essay
"Would the reader still get my point if I deleted that line?"
Ego is the Enemy
book
A welcome reality check. Beware the urge to become enamored with your own success.
How I Realized that Hourly Billing is Nuts
essay
How on earth is a client supposed to know how long it'll take me to do the thing they hired me to do because they can't do it themselves?
Do I truly want to become a manager?
▴back to topessay
Is it just because you want control? Or that you're the smartest engineer on the team? Better think hard about this one.
#Systems
Colocation
essay
When one thing has to change because another thing changed, put them as close as possible together.
A Daily Practice of Empirical Software Design
video
"The cost of software is approximately equal to the coupling. And that's what's being addressed with software design. The reason we design software is so that we can change it... and change it at reasonable cost."
Shipping is your company’s heartbeat
essay
"Software only becomes valuable when you ship it to customers. Before then it’s just a costly accumulation of hard work and assumptions."
Accelerate
book
One of my top recommendations for anyone putting software into production or leading the people who do. Chock full of high-quality research on how to deliver valuable features quickly in a software environment without chaos.
Team Topologies
book
The authors present four different kinds of teams as the basic blueprint, with most teams being the kind that is long-running, crossfunctional, and organized around delivering a particular business outcome.
Squeeze the hell out of the system you have
essay
"Always put off significant complexity increases as long as possible."
Introduction to Systems Thinking
essay
"Redesigning things at the systemic level offers us far more leverage to shape our future than simply reacting to events."
How Complex Systems Fail
essay
A classic. This treatise presents a series of observations about the operation and manipulation of systems that must all be held in tension to get the full benefit.
Systems design explains the world: volume 1
▴back to topessay
"What is systems design? It's the thing that will eventually kill your project if you do it wrong, but probably not right away."
#Product Development
The ultimate guide to JTBD
video
Unlike the typical "build it and they will come" attitude, Jobs to be Done is a radical approach to product innovation that seeks to uncover a customer's struggle and build products and services to help them make progress. Go deep after watching the video and read the book that introduced JTBD to the world, Clayton M. Christensen's Competing Against Luck.
Understanding the B2B vs. B2C and Product Development Formats
podcast episode
Jobs to be Done in context of B2B, especially when the customer isn't the consumer.
Options, Not Roadmaps
essay
Rather than a list of commitments, we should consider future features to be opportunities that we may or may not pursue. That's hard to imagine since so many of our tools tend to encourage linear thinking. I'm especially fond of the author's notion of a product visualized as a map with colored pins that represent the various options before us.
Suitably Detailed Roadmap Items
guide
Don't waste your time planning out every jot and tittle of a project 6 months out from starting it. Most of it won't be relevant by then anyway. So how much is good enough?
Shape Up
book
If sprints and story points aren't working for you, this is a breath of fresh air. This book outlines a different approach to building software that brings clarity, focus, and quality back into the process, and my teams have loved it. If you want a quick overview, I'd highly recommend the author's Shaping in a Nutshell video before reading the book. Then go deeper and learn how Shape Up can be applied in different business contexts with this conference talk.
Don’t Make Me Think, Revisited
book
The seminal book on user experience. It's a must-read for anyone building interactive products.
Diátaxis
▴back to topguide
A helpful framework for writing technical documentation. It presents four different types of docs and emphasizes writing for the audience of each type specifically, avoiding the confusion that often follows from blending them together.
#UI Design
Principle of least astonishment
essay
A wonderfully simple heuristic for designing effective user interfaces.
UI and Capability
essay
While ostensibly about UI design, this essay was instrumental for me in developing a better mental model for identifying the meaningful concerns in a system. "The more you see how each piece of design and code supports a specific capability, the easier it is to find order in the chaos of product development."
Don’t Make Me Think, Revisited
▴back to topbook
The seminal book on user experience. It's a must-read for anyone building interactive products.