Architecture.md (2021)
matklad.github.io
Architecture.md (2021)
1–10 of 54 posts
Re: Architecture.md (2021)
#2> One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project. Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code.
Here here! This sounds like such awesome advice.
I wish we had better tools to visualize architecture of running systems. It's crazy to me that reading the code or a markdown file are still so state of the art. Maybe if someone's fancy they'll have some nice Mermaid diagrams. I want the architecture to be able to show itself live. Broadscale macroscale observability, baked in.
I think this would help everyone be able to appreciate & grok computing much more, would help humanity augment itself.
Re: Architecture.md (2021)
#3> One of the lessons I’ve learned is that the biggest difference between an occasional contributor and a core developer lies in the knowledge about the physical architecture of the project. Roughly, it takes 2x more time to write a patch if you are unfamiliar with the project, but it takes 10x more time to figure out where you should change the code. Here here! This sounds like such awesome advice. I wish we had bett…
I'd like to see something like [dep-tree](https://github.com/gabotechs/dep-tree) 's visualization augmented with a keyword or LLM vector search. Your query would highlight relevant files and clusters.
Re: Architecture.md (2021)
#4I 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.
Re: Architecture.md (2021)
#5> If you maintain an open-source project in the range of 10k-200k lines of code, I strongly encourage you to add an ARCHITECTURE document
I like this idea but IMHO, regardless of repo size, architecture can still has some place in a Readme. For example, I purposely placed a Mermaid sequence diagram[1] in the main Readme because I think it's important that all readers see and understand its workflow[2]
[1] https://mermaid.js.org/syntax/sequenceDiagram.html
[2] https://github.com/hbcondo/revenut-app?tab=readme-ov-file#-w...
Re: Architecture.md (2021)
#6My experience was that on every project I was onboarded I was shown such an architecture diagram with a brief explanation of its components.
Now I'm surprised how uncommon this is in open source.
Re: Architecture.md (2021)
#7My experience was that on every project I was onboarded I was shown such an architecture diagram with a brief explanation of its components. Now I'm surprised how uncommon this is in open source.
The "explanation of its components" is the problem: someone needs to do it. Open source projects don't have an employee's first day, so they don't have this introduction.
They're not good if you don't have a sea of time, though. (An employee is expected to take a few weeks before getting anything done on their own.) I'm a security consultant, so we get to see a brand new one of these every two weeks and the problem with these explanations is that they are ad-hoc, unstructured, and mention lots of irrelevant details because the speaker has the curse of knowledge.
Perhaps someone new to the repository should write this thing once, after which it can just be maintained. Second best is to just have anybody write it down, taking a minute to think about what goes in there and what doesn't rather than doing it always on the fly, because as the author says:
> this file should describe the high-level architecture of the project. Keep it short: every recurring contributor will have to read it. Additionally, the shorter it is, the less likely it will be invalidated by some future change.
Re: Architecture.md (2021)
#8Random thought: Every IDE I've used gives me the folder structure of the project on the left as a standard directory tree. Does any support navigating a project as a graph of dependencies?
Re: Architecture.md (2021)
#9 the shorter it is, the less likely it will be invalidated by some future change. This is the main rule of thumb for ARCHITECTURE — only specify things that are unlikely to frequently change. Don’t try to keep it synchronized with code.
I agree it is the difficulty in grokking a codebase. "Pattern" naming sort of helps, but I end up having to read a far bit.
On github, I always keep thinking the commit messages for each file are descriptions. Would that be more useful?
Re: Architecture.md (2021)
#10Random thought: Every IDE I've used gives me the folder structure of the project on the left as a standard directory tree. Does any support navigating a project as a graph of dependencies?
What would that practically look like? How would circular dependencies be resolved, for example?