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

Architecture.md

matklad.github.io

Post reply on HN
Print view View original

111–120 of 159 posts

Re: Architecture.md

#111

Post by pbkhrv »

jzer0cool wrote: post #110
baby wrote: post #47

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md (or a README if it's not too long), but it's even more dope to be able to click through it and have submaps of how other components are structured. Displaying the folder/file structure and explaining what is what is a must. An example from Diem[1]: consen…

Any well known tools which print above like folder path trees command-line?

On Linux there is a nice little utility called “tree” https://packages.debian.org/stable/tree Not sure about Mac or Windows.

Re: Architecture.md

#112

Post by house9-2 »

jzer0cool wrote: post #110
baby wrote: post #47

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md (or a README if it's not too long), but it's even more dope to be able to click through it and have submaps of how other components are structured. Displaying the folder/file structure and explaining what is what is a must. An example from Diem[1]: consen…

Any well known tools which print above like folder path trees command-line?

tree

brew tree (if you are on Mac)

Re: Architecture.md

#113

Post by euske »

In addition to architecture, I'd strongly recommend to add "GLOSSARY". In many software projects, a certain common noun has a project specific meaning, and it's confusing to a first-time reader who has to figure out which one is a special term. In my own PDF parser project, for example, "stream", "trailer", and "literal" are PDF-specific terms that are different from its normal usage. A glossary also helps introducing basic concepts used in the ARCHITECTURE.

Re: Architecture.md

#115

Post by ablekh »

gregmac wrote: post #103
ablekh wrote: post #55

Earlier quoted context omitted.

I believe that an optimal architectural document should cover both "why" and "how". Having said that, back when I was writing and modifying such documents at a CMM Level 3 division of a large and well-known tech company (using the waterfall SDLC process!), relevant information was split between high-level and low-level design documents. I found it quite inconvenient and think that having relevant sections (with cross…

You need enough "why" so someone reading it doesn't ask, but not so much you're writing a history textbook. Mostly, think about what someone reading this in 6-24 months will think. Without some background reasoning, parts may seem over-engineered and unnecessarily complex. Say the same time, no one will care about the hours of debate that went on, or the shortcomings of the v1 prototype this replaced.

I agree with you that information (IMO both coverage and level of detail) should be balanced, for the target audience. However, I think that it does not apply to "why" information exclusively. Rather, this is pretty much a universal approach / best practice and, thus, should be applied across all categories of content.

Re: Architecture.md

#116

Post by villasv »

DyslexicAtheist wrote: post #5

what they suggest is very similar to Architecture Decision Records (ADR's). https://adr.github.io/ TL;DR: ADR's are a design choice for a lightweight process to store and manage the history over what architecture decisions have been made in the past and why. They should be tracked within git so that the history of decisions and how these evolved is provided for free . Just track all this within an `adr/` subdirectory…

I thought of ADRs too, but it seems the objective here is to be a bit more high level. It doesn’t help that the term “architecture” is so wide in meaning.

I’ve adopted ADRs and it has been good for decision making, but it doesn’t help much new contributors to find exactly what module they need to focus on for a task.

Re: Architecture.md

#117

Post by [deleted] »

jzer0cool wrote: post #110
baby wrote: post #47

I have a similar advice, but I will go one step further: add README.md to other folders as well. It is dope to have a map of your whole system in an Architecture.md (or a README if it's not too long), but it's even more dope to be able to click through it and have submaps of how other components are structured. Displaying the folder/file structure and explaining what is what is a must. An example from Diem[1]: consen…

Any well known tools which print above like folder path trees command-line?

[deleted]

Re: Architecture.md

#118

Post by yjftsjthsd-h »

fukmbas wrote: post #106
utborin wrote: post #29

As someone who is in week two of spooling up on a multi-million-line codebase where most of the original authors have moved on to other projects, please, I beg you to heed this advice. I spend the vast majority of my time figuring out where a change needs to happen. The patches themselves are no more than 10% of the work. (The other significant factor is running tests.)

It's called job security bub. I'm not going to write out everything you need to know. Hire an expert and whatever time it takes him to figure out is how much it's going to cost you to churn through employees. Don't like it? Be a better employer so your employees don't leave.

Lovely - now when you get in a car accident, your teammates get to be upset by losing you and have to reverse engineer the mess you left. Hope you don't plan to ever take vacations either - you're too important to leave.

Re: Architecture.md

#119

Post by Shorn »

I wrote an article recently about a method I use that I call the "funnel architecture". The idea is to concentrate important high-level concepts of your client app's infrastructure into a single file - the intent being to let that stand as a form of documentation of the app's infrastructure/architecture.

https://kopi.cloud/blog/2021/funnel-architecture/

Re: Architecture.md

#120

Post by tcbasche »

londons_explore wrote: post #13

I would encourage people to have one ARCHITECTURE file per directory of source code files. Don't duplicate documentation in these files - if there is a well documented header file for some module, just link to that. In a big project, when I'm hunting for code that does something and I have no familiarity of the codebase, I want to be able to follow a chain of ARCHITECTURE documents from the root of the project to the…

I can almost guarantee either the docs won't get updated, or new source code directories will get created without the ARCHITECTURE file.

At least having a single file means only one file potentially goes out of date, instead of dozens

Post reply on HN