How (not) to write a manifesto
I recently updated the Handmade Manifesto again.
The manifesto is the entry point for newcomers to the Handmade community, a group of programmers working to change the course of the software industry. The manifesto's purpose is to attract people to the community and set the tone for what we're about. The original was written when the community was founded in 2016, and since becoming the community lead in 2022, I've updated the manifesto twice.
It's on its third revision now, and I think it's far more pointed than it was before. It's interesting to look back at old versions of the manifesto and see how our messaging has shifted, so let's compare all three versions side-by-side.
2016
Modern computer hardware is amazing.
Manufacturers have orchestrated billions of pieces of silicon into terrifyingly complex and efficient structures that sweep electrons through innumerable tangled paths, branchings, and reunions with the sole purpose of performing computations at more than a billion times per second. This awe-inspiring piece of computational wizardry has at its disposal multiple billions of uniquely addressible silicon plates where it can store the results of millions of computations in an array of several vanishingly small chips. All of this hardware, though each component often sits no further than 7 or 8 centimeters away from the others, cycles so fast that the speed of light, a physical law of the universe, limits the rate at which they communicate with each other.
2022
Computers are amazing.
Computers have changed our lives for the better. They allow us to learn, connect with each other, and express ourselves in amazing new ways. And every year computers get more powerful, less expensive, and more accessible - computers today can do things we hardly dreamed of twenty years ago.
2023
Computers are amazing.
Computing has changed our lives for the better. Computers allow us to learn, connect with each other, and express ourselves in amazing new ways. And every year our devices get more powerful, less expensive, and more accessible - computers today can do things we hardly dreamed of twenty years ago.
The first version is incredibly wordy. It would be ok if we were writing poetry, but we're writing a manifesto, so almost all of it got scrapped.
You might question whether this paragraph is necessary at all. It would be punchy to start the manifesto with “Why is software so terrible?” But I think it's very important to start with the positive here. We aren't a bunch of luddites who think technology sucks and we should all go become farmers. We like computers, and we are optimistic about what they can do for us.
Also, if we didn't have a positive outlook, we'd just be Suckless, and Suckless sucks.
So why is software still slow?
Why does it take your operating system 10 seconds, 30 seconds, a minute to boot up? Why does your word processor freeze when you save a document on the cloud? Why does your web browser take 3, 4, 10 seconds to load a web page? Why does your phone struggle to keep more than a few apps open at a time? And why does each update somehow make the problem worse?
So why is software so terrible?
Why do web pages take ten seconds to load? Why do apps mess up scrolling? Why does your phone battery still die so quickly? And why does each update somehow make the problem worse?
And why do we all use huge frameworks that no one understands? Why do our projects take several minutes to compile? Why do we have to restart our language servers every twenty minutes? And why does everyone think this is fine?
So why is software so terrible?
Why do high-end gaming PCs struggle to browse the web at 60 frames per second? Why does a simple calculator need a splash screen? Why does your phone's battery still die so quickly? And why does each update make the problem worse?
And why do we all use huge frameworks that no one understands? Why do our projects take minutes to compile? Why do we have to restart our language servers every twenty minutes? And why does everyone think this is fine?
Modern software is bad! This attitude rubs some people the wrong way, but that is a good thing. This is a manifesto; if it doesn't ruffle some feathers, it doesn't mean anything.
But there's a specific angle we care about: software sucks relative to hardware. The new manifesto's examples are focused on this. You can justify why a web page might be slow to load, but you can't justify a 2D website that runs worse than a 3D open-world game on the same hardware.
I've also switched to examples that are more emotionally familiar to people. Operating system boot processes are mysterious and foreign to most programmers, but calculator apps with splash screens are a daily frustration. The new second paragraph appeals directly to programmers' emotions - while we care about more than programming tools, it makes sense to directly address our audience here.
But perhaps the most important change is the heading. The original manifesto said “So why is software still slow?” Now it reads “So why is software so terrible?” The original manifesto was too focused on performance, and we struggled with this perception of “performance at all costs” for a long time. “Why is software so terrible” is better because it's more broad, and appeals to emotions.
A lot of us have forgotten that.
In our haste to get our products, our projects, the works of our hands and minds, to as many people as possible, we take shortcuts. We make assumptions. We generalize, and abstract, and assume that just because these problems have been solved before that they never need to be solved again. We build abstraction layers, then forget we built them and build more on top.
And it's true that many of us think we do not have the time, the money, the mental bandwidth to always consider these things in detail. The deadline is approaching or the rent is due or we have taxes to fill out and a manager on our back and someone asking us why we always spend so much time at the office, and we just have to stick the library or virtual machine or garbage collector in there to cover up the places we can't think through right now.
Others of us were never taught to think about the computer itself. We learned about objects and classes and templates and how to make our code clean and pretty. We learned how to write code to make the client or the manager or the teacher happy, but made the processor churn. And because we did, that amazing speed we'd been granted was wasted, by us, in a death by a thousand abstraction layers.
We made it terrible.
Not necessarily you or me, not necessarily anyone in particular. But we, the software development community, made it terrible through our thoughtless behavior. We ignored the hardware. We glued together libraries so we didn't have to learn. We built layers on top of layers, until no one knew how anything worked.
But worst of all: we put our own desires above the user's.
You may have learned that programming is about classes, monads, or type systems. You may have been taught to keep your code clean and pretty, abstract and future-proof. None of that matters when the end result is garbage.
We made it terrible.
We, programmers, have made it terrible through our thoughtless behavior. We rewrite our apps in new languages, and rather than measure anything, we just assume it will be better. We ship thousands of dependencies to our users to save ourselves a few minutes of effort. We build towers of abstractions, forget how they work, and then build new ones on top.
This isn't engineering. We're building Rube Goldberg machines, and users are paying the cost.
You may have learned that programming is about classes, monads, or type systems. You may have been taught to make your code clean, abstract, and future-proof. None of that matters when the end result is garbage.
I hate this part of the original manifesto. It's so bad. Why does it refuse to attribute blame? Why does it try to placate you and assure you that it's not your fault??? This is the worst manifesto ever.
The 2022 version made it less wordy but kept some of this attitude. But no more. The new manifesto pulls no punches. We made it terrible. We, programmers. It is our fault.
Notice that the 2023 version shifts to the present tense. These terrible programming practices are happening now. I think this makes this section much more resonant. There is no room for complacency - the mess of modern software is our fault, it's getting worse, and we're to blame.
Many people don't agree with this; they like their towers of abstractions. This manifesto is not for them. As with the previous section, this is designed to emotionally resonate with a particular kind of programmer who sees the world the way we do. Better to attract those people than dilute our message.
But some of us aren't satisfied with that.
Some of us take a few extra steps into the covered territory, the wheels sitting, motionless, in a pile behind us, examine their designs and decide there is a better way. The more experienced among us remember how software used to be, the potential that we know exists for computer programs to be useful, general, and efficient. Others of us got fed up with the tools we were expected to use without complaint, but which failed us time and time again. Some of us are just curious and don't know what's good for us. Don't trust what we've been told is good for us.
We sat down and looked at our hardware, and examined our data, and thought about how to use the one to transform the other. We tinkered, and measured, and read, and compared, and wrote, and refined, and modified, and measured again, over and over, until we found we had built the same thing, but 10 times faster and incomparably more useful to the people we designed it for. And we had built it by hand.
That is what Handmade means. It's not a technique or a language or a management strategy, it isn't a formula or a library or an abstraction. It's an idea. The idea that we can build software that works with the computer, not against it. The idea that sometimes an individual programmer can be more productive than a large team, that a small group can do more than an army of software engineers and do it better. The idea that programming is about transforming data and we wield the code, the tool we use to bend that data to our will.
It doesn't require a degree, or a dissertation, or a decade of experience. You don't need an expensive computer or a certificate or even prior knowledge. All you need is an open mind and a sense of curiosity. We'll help you with the rest.
But there is another way.
Some of us aren't satisfied with the current state of software. We think that wheels need to be reinvented. We like looking under the hood, understanding what others take for granted. We remember how software used to be, and know how much potential there is to make it better. We fight against the status quo, because we know how things could be.
This is what Handmade means. It's not a technique or a language or a management strategy. It's not a library or a framework or a paradigm. It's an idea. The idea that we can build software that works with the computer, not against it. The idea that the user matters more than the programmer. The idea that sometimes a small group can do more than an army of software engineers, and do it better.
You don't need a degree, a dissertation, or a decade of experience. You don't need an expensive computer or a certificate. All you need is an open mind and a sense of curiosity. We'll help you with the rest.
But there is another way.
You can break out of this cycle. You can learn how computers actually work, so you can unleash the full potential of modern systems. You can dig deep into the tech stack and learn what others take for granted. When you run into a wall, rather than stop, you can dig under it.
This is our mission. You don't have to be a genius to make your software better - you just have to be willing to learn and willing to go against conventions. We're here to teach you, to inspire you, to help you break free from the mess of modern software development and make software the Handmade way.
And you thought the other sections were wordy.
The previous section was bad, but this is just embarrassing. This is supposed to be the call to action. This is supposed to face the doubts and uncertainty head-on and say “THIS is how you develop software”. But the first sentence is literally incoherent.
The 2022 revision is better, and states things much more directly. But you can also feel how some of the old manifesto is still grafted on, and it states its point too weakly. The 2023 revision finally feels right to me. It directly addresses the reader - you can learn how computers actually work, you can dig deep into the tech stack.
And let's address the elephant in the room: “This is what Handmade means.”
This question has plagued us for years. “What does Handmade mean?” Does it mean to never use libraries? (No.) Does it mean to always use C? (No.) Does it mean to only make video games? (No, dammit!) But the manifesto really did not help us on this point; it just says “This is what Handmade means” and refuses to elaborate.
So no more waffling. Learn how computers actually work, so you can unleash the potential of modern systems. That is what Handmade means.
Will you join us?
Will you build your software by hand?
Will you join us?
Will you build your software by hand?
So join us.
We know how much better software can be. The industry needs to change, and we're going to lead the way. Join us, and learn to build software by hand.
Not much to say here, except that this is an actual call to action. 🙂
When I joined the community years ago, I was a college student confused and disillusioned by the programming industry. The advice I was receiving from my professors and coworkers just didn't make sense. Something was wrong in the programming world, and I couldn't put my finger on it.
Then I found the Handmade community. The original manifesto had its problems, but it resonated with me, and drew me in. And once I joined, my programming career was changed forever. I hope this new manifesto can do the same for others like me.
At the end of the day, the manifesto is just one small piece of our messaging. After all, we're also hosting real-life conferences with major speakers, running jams, hosting fishbowls, and prepping other projects that we're excited to launch soon. But it's important. The manifesto is that first step, to draw people in and set the tone. I hope you find it inspiring, maybe enough to join us.