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

101–110 of 159 posts

Re: Architecture.md

#101

Post by Gehinnn »

Terretta wrote: post #40
alixanderwang wrote: post #35

I think diagrams are usually quite helpful in accompanying an Architecture.md doc, especially if it gets complex. I work on a diagram maker that syncs with a Github repo. So whenever you make changes to this architecture diagram, it'll push changes to the repo, with screenshots directly in the README (turning the repo into a diagram presentation). This also allows people to colocate the diagrams alongside the code or…

An alternative is to use an embedded diagramming syntax like dot or mermaid such that the diagrams are described as version controlled text and optionally rendered inline by e.g. VSCode. Cleaner than a litter of side car images in which it may be unclear what changed. See Markdown Preview Enhanced: https://marketplace.visualstudio.com/items?itemName=shd101wy... Or add Mermaid to the built-in markdown preview: https:/…

Text based diagrams definitively have their advantages over wysiwyg editors. However, sometimes the layout of a diagram also tells a story and I find it hard to express that with available text based diagram solutions.

That's what I use draw.io aka diagrams.net for. I made an extension that helps to create markdown-embeddable/versionable draw.io diagrams in vscode: https://github.com/hediet/vscode-drawio (there is also an IntelliJ extension)

I have to admit that I sometimes struggle with pixel perfect layouts though and rearranging nodes is time intensive.

However, most text based systems don't have a nice github integration and rely on manual export, which you can avoid when you diagram is not a plain text file but a rich diagram editor.

Re: Architecture.md

#102

Post by snicker7 »

jlg23 wrote: post #91
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…

This will help people browsing code in github, but folks browsing code in their IDE will most likely be lost, as the documentation you advice to put into "README.md"s should, IMHO, be in the module/package documentation in the source. One can still link to those from the global README.md

READMEs and API docs aren't mutually exclusive. But they cover different scopes. READMEs are more suited for high-level documentation, focusing on the /why/ instead of the /how/.

Re: Architecture.md

#103

Post by gregmac »

ablekh wrote: post #55
orthoxerox wrote: post #41

Earlier quoted context omitted.

ADRs are more about the "why" (and are absolutely indispensable in any long-running implementation project). Architecture.md is mainly about the "how".

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.

Re: Architecture.md

#104

Post by throw982739182 »

More repos need to do this. If it's not too big it can be stuck in development.md which is where I usually stick it.

It makes it so much more likely that I'll contribute with a proper PR. There's some codebases I would have liked to contribute to but they were so complicated and with so few comments I just gave up and only reported the bug / made a feature request. Even worse when they have complicated undocumented build systems.

Re: Architecture.md

#105

Post by bombcar »

baby wrote: post #87
michael_j_ward wrote: post #73

Earlier quoted context omitted.

When I first started programming, I thought the description next to the folder / file name on github was actually describing the item - as you did above, and not just the message from the last commit that altered the file. Many years later, I still believe that's how it should be.

Agree! I gave that feedback many times, who cares about commit message? I want documentation here! I think Github should really start taking a stance on convention, and come up with project structure conventions that would help project navigation. For example, youtube does that with chapters in videos, if you write a description with timestamps it will display these chapters in the timeline of the video[1]. IMO Githu…

I’ve recommitted a number of times just because the last commit message was dumb or useless or worse - wrong.

Re: Architecture.md

#106

Post by fukmbas »

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.

Re: Architecture.md

#107

Post by amw-zero »

matklad wrote: post #68
amw-zero wrote: post #56

Earlier quoted context omitted.

Oh, so the solution is to just add another thing to “remember” to do. That must be what I’ve been missing all these years. Yes, that’s extra thick sarcasm.

I disagree with this characterization. ARCHITECTURE.md is specifically engineered to be low churn, so in this respect it is meaningfully different from other “keep docs” advise. In practice, I personally didn’t find it difficult to maintain half-decent ARCHITECTURE.md, and I am not at all good with keeping the docs otherwise.

> specifically engineered to be low churn

This is not actually possible. You're kidding yourself if you think such a document is "future proof."

Re: Architecture.md

#108

Post by AnonC »

The bird’s eye view seems to be an image, at least in the example cited there. A picture can tell a thousand words and can set a good context for the words that follow. What are the easier ways (amenable to easy creation and modification) to make it accessible for people having issues with vision?

Re: Architecture.md

#109

Post by baby »

jlg23 wrote: post #91
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…

This will help people browsing code in github, but folks browsing code in their IDE will most likely be lost, as the documentation you advice to put into "README.md"s should, IMHO, be in the module/package documentation in the source. One can still link to those from the global README.md

I'm not sure I understand why someone in their IDE would be lost, you can't read README.md and see the file structure in your IDE?

Documentation in the source is different from a directory organization documentation IMO. Rust has a lot of tools to write good documentation in source, and it is here to help produce good documentation for users of a library, not to explain how to contribute to the code or understand how everything is architected.

Re: Architecture.md

#110

Post by jzer0cool »

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?
Post reply on HN