Show HN: I published a book to save you from my software architecture mistakes

Re:Show HN: I published a book to save you from my software ... by mjovanovic0 on Monday August 26, 2024 @12:44PM (#41359020)

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.

[ Parent | on HN ]

Re:Show HN: I published a book to save you from my software ... by meaboutsoftware on Monday August 26, 2024 @12:58PM (#41359173)

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.

[ Parent | on HN ]