Show HN: I published a book to save you from my software architecture mistakes(leanpub.com)
leanpub.com
Show HN: I published a book to save you from my software architecture mistakes
https://leanpub.com/master-software-architecture
33 comments
Merely for your consideration, if you created a GitHub repo and put that sample PDF in there instead of Google Drive, it would not be subject to rate limiting as Drive links are and would also make your book show up in GitHub searches, which I would suspect contains a lot of your target audience. Don't overlook the value of adding GitHub "topics", too, which are often a way projects get discovered: e.g. https://github.com/topics/software-architecture
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
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
Great idea - I already have a repo for the book where I store diagrams. I haven't thought about it. I will move it there.
Thank you!
Thank you!
Then you could also sell it on my platform https://gitsell.dev for way less than the ~20% fee you pay leanpub.
So, two things:
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. 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
Just want to let you know I took your advice and enabled drive-by purchases. Thanks a lot.
Thanks for trying it out.
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.
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.
Congrats on publishing! :)
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.
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.
Thank you! :)
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 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.
Congrats on finishing the book! 400 pages in 5 months is insane levels of productivity. I'm very jealous!
Thank you! This would not have been possible without stopping almost all other work.
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 ;)
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 ;)
Ideally you would design your architecture with the realization that every architecture will become inadequate over time. So basically, design things so you can rip out various parts of it when the time comes.
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'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.
Thanks for your input - the evolution of the architecture is the apple of my eye. The demo part of the book comes from the evolutionary architecture step, which is described on around 100 pages.
I hope you will enjoy it!
I hope you will enjoy it!
Thank you for publishing the free chapter, it felt very down-to-earth and relatable. Looking forward to reading the rest of it!
Thanks! That was the idea of the book - no philosophy, just practical stuff
We need more books of this nature. The free chapter didn't really sell me on the book, but for $26 even if there's only one insight I pick up it may be useful. So I picked up a copy, but I do have some concerns.
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.
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.
Thanks for this comment. It is important to consider everything you said. CQRS is part of this book, but it is more of an explanation and might help you at some point (but does not need to). I think that's the main problem of CQRS - it is not understood well.
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).
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).
The sample chapter doesn’t really give me much confidence that I will learn anything new from _your_ mistakes.
Suggestion: make some more chapters free so potential readers can better gauge how useful it will be.
Suggestion: make some more chapters free so potential readers can better gauge how useful it will be.
Thanks for the tip! The book describes the approach that helps prevent my mistakes, and in each "step," I add several warnings and information sections about what to do and what not. I will try to think of how to add a better demo.
Congrats on releasing the book! It's already a huge accomplishment :) Wishing you to reach as many eager architects as possible and to have fun in exploring SA further.
Thank you Marcin!
One of the first books that seem very interesting to read, coming from a recently graduated student. Will give this a go
Does 10 years count as a recently graduated student? Thanks, I feel very young again! :)
I think the commenter was referring to himself.
Congratulations on finishing the book! It's never an easy thing to accomplish.
Thank you very much!
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 :)
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 :)
It doesn’t work like that. Your mistakes were unique to your experience and situation. You can’t extract them into abstract rules and make a book to give to people. They need to make their own mistakes. And they’ll find out that what was a mistake for you will work for them.
I wish you a lot of success in your publication though, may this be a good source of passive income and give you financial independence.
I wish you a lot of success in your publication though, may this be a good source of passive income and give you financial independence.
I promise you that there is some objectivity in software architecture, and that you can indeed extract useful information from books.
Remember, use composition over inheritance. Except if using inheritance makes sense ;)
Design patterns: composition inspite of inheritance
Nice one!
While I agree that people need to make mistakes (giving newbies room TO make those mistakes is an important part of mentorship imo), I couldn't disagree more with the idea that there's nothing to learn about architecture from a book.
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.
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 partially agree with you- nothing is better than working on "your own" mistakes, but some mistakes often repeat in software architecture. Why not take advantage and not repeat them by learning from others' mistakes? :)
Bizarre comment, of course there's value here
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