The BEAM Book Is Almost Done. Here’s What Writing It Taught Me.

Reflections on scope, clarity, and the joys of letting go.

The Project Nears Completion

I set out to document everything I knew about the BEAM, and to discover everything I didn't yet know. I thought it would be straightforward: outline the architecture, show some code, sprinkle in a few anecdotes. Then I discovered how challenging it is to make concurrency, schedulers, and message passing sound simple.

The manuscript is now nearly complete. I’m fine-tuning the final chapters and making sure the structure doesn’t collapse under its own ambition. It turns out, writing about concurrency requires you to manage your own concurrency crisis: the steady flood of ideas vs. the reality of limited pages and time.

Clarity Over Complexity

Early drafts tried to cover every corner case. I believed completeness was the gold standard. But readers gravitated to the simpler chapters, the ones that made a single concept click. I realized that the trick to explaining concurrency is being hyper-focused on practical examples, then trusting readers to explore deeper if they choose. If I can’t make a concept accessible to a motivated beginner, maybe I don’t understand it well enough.

It turns out there were quite a few of those concepts...

Reigning in the Tools

At one point, I considered writing entire sections on every tracing flag, every debug mode, and every esoteric performance trick. The problem is that readers don’t need an encyclopedia; they need reasons. Tracing is important because you suspect a race condition. Profiling matters because you’re chasing a sneaky performance bottleneck. Tools are only interesting when they solve real problems, so that became my new guiding principle.

Ruthless Scoping

I had to remove or postpone entire topics: dirty schedulers, advanced NIF usage, and extended ERTS internals. They’re fascinating but not essential to the book’s main goal. Each time I felt guilty about cutting something, I remembered that overwhelming readers helps no one. The hardest part of writing isn’t the explaining, it’s choosing what to leave out.

Final Touches

I’m wrapping up the final chapters, polishing details around logging and monitoring to reflect the latest OTP releases. The open source version is already up on GitHub under Creative Commons, where I push new updates as soon as they’re ready.

See theBeamBook.

Once the manuscript feels rock-solid, I’ll bundle it into a formal 1.0 release. A print edition will follow for those who still enjoy the feel of paper or need something sturdy to stop the table from wobbling.

How You Can Help

If you’ve skimmed any parts of the work or tried some examples, I welcome your feedback. Tell me if something is too dense, too vague, or too boring. Yes, that last category is real, and I’d rather know before the book hits the press.

Conclusion

Writing this book taught me to finally stop adding things, cut what's unnecessary, and accept when it's good enough.

If the book helps someone troubleshoot a gnarly bug or finally understand why the BEAM is so special, it’s done its job.

Thanks to everyone who has shared feedback and encouragement along the way. You’ve shaped this project more than you know. And if you discover something confusing, or you see a spot where you’d love more detail, let me know before I release the final print version. Writing about concurrency is fun, but improving it with your input is even better.

Want a heads-up when the print version drops? Just email info@happihacking.se and I’ll add you to the list.