Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Ask HN: Are there any openly available software architecture documents?

news.ycombinator.com

Post reply on HN
Print view View original

21–30 of 53 posts

Re: Ask HN: Are there any openly available software architecture documents?

#21

Post by davengh »

billfruit wrote: post #14
Ididntdothis wrote: post #7

Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process

But then it is all .. vague. I do hope something better than can be done.. hand drawn diagrams can't represent details at different levels of magnitude, like for example why statecharts are very expressive compared to other diagrams is it's ability to have arbitrary levels of nesting, which is not possible with handdrawn or even printed diagrams. I feel like resorting to simple hand drawn diagrams, is in a way declar…

The details will always have to be looked at by the inheritors - it's more important to not say something wrong or contradictory IMO. When I've had to do something like this in the past I circle through it, documenting the high-level ops before details anywhere. Tricky or especially complicated details next, then the operational details for as much as I've time for.

I'm doing this now for a couple of things I've inherited because my predecessors either never documented it or it's been lost to time. High-level flow, tricky and/or problematic bits with operational & recovery info, then the mundane as I have time. That means the mundane or some of the less-tricky tricky bits will be "vague" for a while.

Re: Ask HN: Are there any openly available software architecture documents?

#24

Post by nemetroid »

Ididntdothis wrote: post #7

Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process

I agree. I used to work on a project where everyone involved in the initial design had left the company, and documentation was spotty. The major issues I had working with the code were all related to not understanding the underlying design choices, e.g. why a certain model was chosen over another or how a certain abstraction was intended to be extended with new functionality.

Stuff that can be formalized in a systematic manner is usually stuff you can figure out on your own in a text editor or IDE.

Re: Ask HN: Are there any openly available software architecture documents?

#26

Post by lanstin »

Most important thing to convey is the conceptual framework used and assumptions made to simplify things. e.g. "We will fix problems only by altering the base image, not the build system." "We will not change to 64-bit build as a part of this change." The sort of thing so that if someone really internalizes the perspective, they will be able to decide all the details on their own. Also a basic picture is always very popular. The details should be in git someway or another, but being able to use the details quickly is the job of the overview. I find it useful to document common change workflows ('To add another type of processor, add the class name to this map in this file, provide a jar implementing that class here, and add a new ID to the enum here.')

Re: Ask HN: Are there any openly available software architecture documents?

#27

Post by mthoms »

claudiulodro wrote: post #22

There are dozens at the Architecture of Open Source Applications ebook/site: http://aosabook.org/en/index.html As someone who only really gets exposure to web tech, it was fascinating how other types of software is architected, too.

Wow, what a great resource. Thanks for sharing.

Re: Ask HN: Are there any openly available software architecture documents?

#29

Post by throw_14JAS »

billfruit wrote: post #14
Ididntdothis wrote: post #7

Don’t do it like me and overthink it. Just write down all your thoughts informally. Make diagrams by hand. Only once you have most content then think about formatting and structure. A lot of people produce nicely looking docs without much content. I much prefer a bunch of simple notes that describe the thought process

But then it is all .. vague. I do hope something better than can be done.. hand drawn diagrams can't represent details at different levels of magnitude, like for example why statecharts are very expressive compared to other diagrams is it's ability to have arbitrary levels of nesting, which is not possible with handdrawn or even printed diagrams. I feel like resorting to simple hand drawn diagrams, is in a way declar…

What works for me is to do things by hand, until all the possible information I might want to share is present. I call it my inventory.

Then work on refining, editing, deleting, modifying.

Separate the creation from the editing/communication.

Re: Ask HN: Are there any openly available software architecture documents?

#30

Post by davalapar »

There are bunch of them, really.

But for general structure, using your end-user's user experience path (from start to end) as a guide and avoiding buzzwords as much as you can usually help. Think of Stripe's documentation, you want something as easily digestible as that.

- Software Design Patterns: https://en.wikipedia.org/wiki/Software_design_pattern

- Azure Application Architecture Guide: https://docs.microsoft.com/en-us/azure/architecture/guide/

- Azure Cloud Design Patterns: https://docs.microsoft.com/en-us/azure/architecture/patterns...

- Azure Architecture Framework: https://docs.microsoft.com/en-us/azure/architecture/framewor...

- Azure Cloud Adoption Framework: https://docs.microsoft.com/en-us/azure/cloud-adoption-framew...

- Cloud Computing Patterns: https://www.cloudcomputingpatterns.org/

- Microservice Architecture Patterns: https://microservices.io/patterns/index.html

- Amazon's Builders Library: https://aws.amazon.com/builders-library/

Post reply on HN