Show HN: I published a book to save you from my software architecture mistakes (leanpub.com)
I just wanted to share that after five months of intense work and countless caffeine-fueled writing sessions, "Master Software Architecture: A Pragmatic Guide" is now available.
Writing this book was a crazy time. I entirely focused on it, and it took exactly 753 hours of writing, editing, and image editing & resizing(!) until the premiere.
Yes, the last one (images) was a killer. If you ever think about writing a book, reserve a lot of time for it unless someone else does it for you.
As a result, I am handing you the nearly 400-page book. It is a guide that will help you connect all the pieces while balancing the focus on understanding the domain and technology aspects, described using a pragmatic approach and super simple language.
It is perfect for novice architects taking their first steps in software architecture. It is also an invaluable resource for software engineers looking to understand architectural concepts and those considering transitioning into an architect role.
Several guest authors, including Vlad Khononov (Learning Domain-Driven Design book), Oskar Dudycz (Marten, Emmett, Pongo), and Milan Jovanović (.NET & C# educator), shared their views on keys to successful software architecture.
Here you can find a free chapter (the first link on this page):
https://www.fractionalarchitect.io/books/master-software-arc...
To your success, Maciej "MJ" Jedrzejewski
33 comments
[ 26.3 ms ] story [ 1412 ms ] threadI wish you a lot of success in your publication though, may this be a good source of passive income and give you financial independence.
A vast majority of the mistakes people make are avoidable ones stemming from ignorance. They're often missing the "why" part of architecture. "What does it mean for an architectural choice to be 'good'?" This can 100% be "book learned" and then mastered through the messy process of experience. You have to at least know the rules to play the game. Many people skip the "know" part.
I actually don't know if LeanPub has its own errata and issue tracking system, but a lot of authors also use GitHub issues for tracking feedback from their editions, so if that's something which interests you then you'd have one stop shopping for all community interactions around your book
1. Pushing Buy on <https://gitsell.dev/u/bitofbreeze/r/bitofbreeze/git-sell> just spins and there is no information on the screen, nor any kabooms on the devtools
2. It also seems from your free "test" link that it's not selling content it's selling access to the repo, which requires buyers to already have a GitHub account and thus is absolutely incomparable to "drive by" purchases. I could imagine that being a better story for long-term relations, like priority support and edition updates, but again, it's just simply not the same audience
Anyway, the reason I was trying the Buy button is because LeanPub has a slider for "pay what you want" within the bounds set by the author. Some authors have the lower bound set to $0 so it is quite literally pay what you want. I doubt your system would allow that same flexibility
1. I’m seeing a toast when logged out saying to log in to buy. It only shows the first time, I can improve that so that if someone misses it the first time and tries again they can see it.
2. Great point, I can add support for drive-by purchases. Either allowing downloading a copy of the repo or generating an ssh key someone can clone the repo with.
Yea my system does not currently allow flexible pricing, it’s free or for a set price. I have plans to support it too.
Thank you!
Suggestion: make some more chapters free so potential readers can better gauge how useful it will be.
I'll probably get a copy, just because I might learn something interesting.
In the end, the point isn't to learn software architecture, it's to learn the thought process behind software architecture.
I hope you will enjoy it!
I tried to keep writing daily—sometimes for just 4 hours, sometimes for 13. On average, it was more than 8 hours a day, with some longer (1-week) breaks in between.
I will write another post on writing experience in the next few weeks :)
This is my tip: if you want to write a book, plan unpaid holidays, or stop all consulting/freelancing work. Then, it is not that hard to keep up the tempo - when you know what you are writing about, of course ;)
Does your book include a section(s) on how to document software architecture? What I’ve encountered is a variety of methods for documenting things, to the point where the documentation becomes outdated, unread, and ultimately a mess.
I'm looking for guidance on properly documenting a system, both during the design phase and for tracking changes and decisions. I'm thinking of something along the lines of design documents, Architecture Decision Records (ADRs), and similar methods.
I have similar observations, and over the years, I kept looking for something that would stand the test of time. I still remember horrors related to documenting architecture in Word documents (and requirements in Excel, omg).
The architecture decision log usually works well for the teams I work with. It is kept up to date and ordered thanks to architecture decision records.
I describe it extensively in one of the book's chapters with a practical example. I also show how to document alternatives considered when the record was added, where to keep it in case of mono repo, multiple repos etc.
I've been pretty cautious about technology decisions. When some new tech gets hyped up, it automatically gets flagged in my brain almost like spam or some infomercial product. Everything has tradeoffs and if the whole industry is telling me I must do X without stating any of the downsides of X those red flags go up. I'll use my own judgement to see if X makes sense. And for the last decade or more I feel I've been on the right side of history. I read the free chapter and the immediate concern is the next chapter which dives into CQRS. CQRS is one of those technologies that was massively hyped up and I'm sure caused lots of projects to fail. Search HN on CQRS and it typically falls into "architecture mistakes" more often than not. So I'm hoping the book is very careful in its recommendations or at least dives into some tradeoffs.
One side note: I slightly disagree a bit with the free chapter's "four steps of evolution". The app I'm building has a very complex domain such that we don't have many competitors and the barrier to entry is high. You can't simply build an MVP that does some small subset and hope to add as you grow as the product would not be functional. You need to handle the domain complexity up front just to deliver an MVP that does some bare minimum. So perhaps this app or industry may be an edge case, but perhaps some caveat is needed in that chapter.
Throughout the book, I describe many concepts. Sometimes, I give some recommendations, and sometimes, no.
I accept your note—these four steps of evolution help you find yourself in one of them. Simplicity can be solved in multiple different ways; it is just the direction of keeping the solution as simple as possible (sometimes it will be more complicated, and sometimes less).
Enjoy reading it; if you don't like it, you can always return it within 60 days (Leanpub policy).