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

31–40 of 53 posts

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

#31

Post by beamatronic »

throw_14JAS wrote: post #29
billfruit wrote: post #14

Earlier quoted context omitted.

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.

This x1000

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

#32

Post by cgarvis »

I found the 4+1 architecture docs very helpful when working with a recent client. https://en.m.wikipedia.org/wiki/4%2B1_architectural_view_mod.... What I like about it is that it separates the architecture into four views each for a different audience

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

#34

Post by godelmachine »

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.

Highly recommend AOSA

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

#35

Post by abhayb »

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

You're absolutely right about not overthinking. Any architecture doc is better than none. Even if the thinking it describes is incoherent or if it describes coherent thinking sloppily. And even during editing, there's only one thing I want my principal engineer to keep in mind. Inside the technical vision, tell me a little about implementation details. Either pulled in from below or, if the principal is risen from my ranks, written from experience.

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

#36

Post by harshulpandav »

Making use of colors in architectural diagrams really add depth to the information. Often applications involve internal and external (out of scope) components. Using common colors for each group of components really helps in the readability.

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

#37

Post by ignoramous »

davalapar wrote: post #30

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…

Apache Kafka's documentation is pretty good, too: https://kafka.apache.org/0102/documentation.html

Also, for a 10,000 foot overview of popular open-source tools, see https://aosabook.org

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

#39

Post by mindcrime »

I am a fan of Phillipe Krutchen's[1] "4+1" model[2], or variants thereof. The book Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives[3] by Eoin Woods and Nick Rozanski is a really good overview of the overall mechanism.

Also, while this bit is probably overkill for your current situation, you may find value down the road in looking at some of the various "architecture frameworks"[4] and reference models that are out there. Things like TOGAF[5], DODAF[6], MODAF[7], TRAK[8], etc.

In any case, always remember the words of the immortal Bruce Lee:

“Absorb what is useful, discard what is useless and add what is specifically your own”.

[1]: https://en.wikipedia.org/wiki/Philippe_Kruchten

[2]: https://en.wikipedia.org/wiki/4%2B1_architectural_view_model

[3]: https://www.amazon.com/Software-Systems-Architecture-Stakeho...

[4]: https://en.wikipedia.org/wiki/Enterprise_architecture_framew...

[5]: https://en.wikipedia.org/wiki/The_Open_Group_Architecture_Fr...

[6]: https://en.wikipedia.org/wiki/Department_of_Defense_Architec...

[7]: https://en.wikipedia.org/wiki/MODAF

[8]: https://en.wikipedia.org/wiki/TRAK

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

#40

Post by doctor_eval »

I’m a huge fan of code as design [1], so I tend to do my architecture thinking at a high level - the objects and interactions between systems - and then write clear and simple code which expresses my intention. To this end, if the code is clear then it doesn’t need to be documented heavily.

I’m also a big fan of DDD [2] and use his “box and line” drawings all the time. There are loads of resources for DDD but I’ve linked to the book, which is awesome. DDD has great concepts like Context Boundaries and Ubiquitous Language which may simplify the documentation process.

It’s easy to think of architecture too abstractly or in terms of frameworks or other complexifying concepts, but simple is good, and that’s true from top to bottom.

[1] http://www.developerdotstar.com/mag/articles/reeves_design_m...

[2] https://www.goodreads.com/book/show/179133.Domain_Driven_Des...

Post reply on HN