I would also look at "The Architecture Of Open Source Applications", although it might be more detail than you're looking for.
Ask HN: Are there any openly available software architecture documents?
11–20 of 53 posts
Re: Ask HN: Are there any openly available software architecture documents?
#12Don’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
So much this. Working for Enterprise I saw so many 20 page architectural documents that were borderline impossible to parse and were about as illuminating as a 30 second conversation.
Re: Ask HN: Are there any openly available software architecture documents?
#13Archi software to draw Archimate diagrams.
Re: Ask HN: Are there any openly available software architecture documents?
#14Don’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 declaring failure on being able to describe complex software requirements and structure/ behavior in a systematic graphical manner.
Re: Ask HN: Are there any openly available software architecture documents?
#15There is the excellent Architecture of Open Source Applications book, which is available online for free at http://aosabook.org/en/index.html
It contains architecture overviews of many open source projects.
Re: Ask HN: Are there any openly available software architecture documents?
#16Don’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…
Just make sure your stuff really expresses something and isn’t just pretty as I see quite a bit.
Re: Ask HN: Are there any openly available software architecture documents?
#17I agonized over the best way to do this stuff for a while also and the best framework I've used so far is the C4 model (as mentioned elsewhere).
For documenting decisions on architecture this should be done as you go really but better late than never :). Using adr ( architecture decision records ) text / md files would be my approach. They will typically be kept alongside the code and source controlled
Re: Ask HN: Are there any openly available software architecture documents?
#18This might initially look to be be a little too specific for military / aerospace, but it can act as a good guideline for a table of contents and examples of what might go in each section.
https://github.com/VCTLabs/MIL-STD-498/raw/master/MIL-STD-49...
The US Military came up with their own standard for systems and software development (MIL-STD-498), which as evolved into IEEE and ISO standards. The nice thing about the US Military's standards is that they came with Data Item Descriptions (DIDs) that specify exactly what goes in each document.
Re: Ask HN: Are there any openly available software architecture documents?
#19Plantuml for drawing pictures together with the C4 Plantuml Plugin is helpful. i.e. you make high level overviews of your architecture and then „zoom in“
For decisions a table with some explainatory comments why you have decided to use this one thing and which alternatives you have considered and why those did not make it, helps. You can look up ADRs. (Decision Records)
Re: Ask HN: Are there any openly available software architecture documents?
#20Our design decision documents have essentially four sections: Problem description, solution options, comparison of the options, and decision. I find it helpful to clearly distinguish what is part of the problem and what part of the solution. The size of the sections varies a lot.
Meta information could be: Status, stakeholders, decision-makers, and rollout description. It also often has links to meeting protocols and tickets.