Discussed at the time:
Architecture.md - https://news.ycombinator.com/item?id=26048784 - Feb 2021 (153 comments)
Architecture.md (2021)
41–50 of 54 posts
Re: Architecture.md (2021)
#42I was a fan of all these little docs/diagrams-as-code standards:
- README-driven development
- ARCHITECTURE.md
- ADRs
- arc42
- C4
- etc.
Instead of using somebody else’s standard, I just organize and refactor docs as I go, in the same way as I manage my personal notes in Obsidian.
Initially I wanted to use a common subset of Markdown that will work both in GitHub (GFM) and Obsidian, but then I gave up, and just use Obsidian flavor of markdown with all its proprietary features like Dataview plugin, templates, etc.
Mermaid and LaTeX is built-in in Obsidian, and there is a plugin for PlantUML.
For visual drawings/diagrams there are builtin Canvas, DrawIO and Excalidraw.
Re: Architecture.md (2021)
#43Rip_hoan903
Re: Architecture.md (2021)
#44Earlier quoted context omitted.
We have those pointless documents used by architects at my place of work, most of them have something on the lines of, Micro services, Kafka, Kubernetes, because what if we have a billion users compared to the current 4k users. GraphDB, what if SQL would not be enough ElasticSearch, what if we have to do full text search along with stats. But most of these documents are just short for any of these, "I want to try thi…
Uh, sounds like these documents are the opposite of pointless, and are in fact working exactly as intended.
depends on the likelihood of those "what if" questions.
A bif chunk of good architecture is judgement: navigating the path between "building for the future" and YAGNI. It's much easier to end up at one end or the other, for example:
* k8s and microservices and sharded, cached data storage and Angular and NX in case we get to internet scale.... on our internal web app with max 400 users
* we're not gonna use a database because we don't know we'll need one... on an accounting system that needs to handle 1000s payments per hour.
I've seen both. I read GP's post as: we have ADRs that justify paying the complexity task when the balance of probability/evidence doesn't justify it. Good judgement is hard. It's one area where good devs/architects can make a really meaningful impact.
Re: Architecture.md (2021)
#45I would be wary of extrapolating what the author is writing of here to general software projects. I think it makes a lot of sense on large open source projects, where there are many contributors with little context- it is worth the effort to maintain such a document in this case. But all the developer committed documentation I've seen on smaller work projects have inevitably become unmaintained.
I've done a few Architecture sessions with teams. It's always valuable.
If anything, you'll learn that people in the team have very different ideas about the current and the ideal architecture. Making that explicit, alone, is worth a document.
And also: "documentation become unmaintained" is a very poor argument to not make documentation. Because any documentation, even outdated or subtly wrong one, is better than "no documentation".
Re: Architecture.md (2021)
#46In my company we called it `COMPASS.md`
Compass cause it helped you navigate. It's short. Every 'module' needed to have such a file. It was also enforced in the CI.
Re: Architecture.md (2021)
#47Earlier quoted context omitted.
Uh, sounds like these documents are the opposite of pointless, and are in fact working exactly as intended.
depends on the likelihood of those "what if" questions. A bif chunk of good architecture is judgement: navigating the path between "building for the future" and YAGNI. It's much easier to end up at one end or the other, for example: * k8s and microservices and sharded, cached data storage and Angular and NX in case we get to internet scale.... on our internal web app with max 400 users * we're not gonna use a databas…
More concretely, if I was asked to consider rearchitecting a service that documented that it "used elastic search just incase full text search was needed" and that requirement never materialized, I'd feel much more comfortable dropping ES than if I was going in blind.
Re: Architecture.md (2021)
#48Earlier quoted context omitted.
The two usual ways I've seen it is either by following the code/control-flow (calls or inverted as called by) or by following the data flow. You can select any code function and see the call (or called) graph (shown as a tree) , similarly for any data element and see the data elements that use (or is used by) graph and pruning cycles.
Call hierarchy trees usually cut cycles with a "there is already a node for this method elsewhere in the tree" end stop.
Is this meant so say it's good, bad, or just is? (which is what I meant by pruning cycles).
Re: Architecture.md (2021)
#49Re: Architecture.md (2021)
#50Earlier quoted context omitted.
Uh, sounds like these documents are the opposite of pointless, and are in fact working exactly as intended.
depends on the likelihood of those "what if" questions. A bif chunk of good architecture is judgement: navigating the path between "building for the future" and YAGNI. It's much easier to end up at one end or the other, for example: * k8s and microservices and sharded, cached data storage and Angular and NX in case we get to internet scale.... on our internal web app with max 400 users * we're not gonna use a databas…
I was being a bit of a prick with my comment, I could've written it more clearly. Sorry for that. My point is this: what do you think is likely to happen if the requirement to write these documents is removed?
a) In the absence of an impetus to justify architectural decisions, people cease creating overengineered architectures.
b) People with an inclination to overengineer systems continue to do so, without documenting their reasoning.
If (a) is plausible, maybe the documents are indeed pointless (or worse). I'm arguing that (b) is far more likely, and it's a strictly worse state of affairs than one in which decision records are written.