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

121–130 of 159 posts

Re: Architecture.md

#121

Post by ryanSrich »

closed wrote: post #18

I love architecture docs, but find they're often written using a funny process: 1. Spend a long time writing the doc. 2. Wait for a person to chance upon it. 3. Hope you anticipated their questions. It seems like the most important thing a person can do is reverse this: 1. Say who the doc is for. 2. Find that person. Ask them to try a lil contribution. 3. Frantically write / revise the doc. IMO it's a lot like creati…

Most documentation follows that first path. With a step 4. that is basically "only update this when something is broken, or when we're hiring someone new".

Doing documentation well, especially if you're working on brand new tech, is very frustrating and difficult. You're often moving too fast to find the time to retroactively update documentation, and you're right back into the viscous cycle of it constantly being out of date. I don't know what the solution is.

Re: Architecture.md

#122

Post by max_ »

Why don't specifications like TLA+ become standards in the dev industry?

It can sort out alot of these issues that have todo with clearly articulating how complex software works.

Re: Architecture.md

#123

Post by benjaminjackman »

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…

This makes me think we should be able to put something like a standard tag for a 1-line summary (maybe embedded in some markdown in a comment) in a fashion the VCS's can detect & extract and then render in their UXs.

e.g. something very simple would probably work like the first line found that matches something like:

   [Ignore_Non_Words]Summary[IgnorePunctuation&Spaces](Capture)

Re: Architecture.md

#124

Post by IgorBog61650384 »

tejohnso wrote: post #86
Spearchucker wrote: post #36

Earlier quoted context omitted.

Thanks for putting that out there. It's super interesting to see what we consider architecture to be. Your approach appears operational, focused on how the completed system functions, i.e. getting a new team member up to speed on the codebase. Typically I try to start with tiers (1, 2, n-tiers...?) that show how the system might be deployed. I then list list layers (user/facade/business/data), interfaces between thes…

Your approach seems like it would reduce the likelihood of implementation-time surprises. It also seems like different sections would satisfy different audiences. Do you have any book recommendations?

Two books I that were instrumental for me to learn how to explain the architecture of my software clearly to other people were "The Architecture of Open Source Applications" Volumes I and II (http://aosabook.org/en/index.html)

Re: Architecture.md

#126

Post by 0xbadcafebee »

kortilla wrote: post #70
FourthProtocol wrote: post #50

Earlier quoted context omitted.

Critical outcomes are defined by quality objectives (I mentioned some above, others are reliability, robustness and portability). People don't consider using my project. There's a client with a business problem, there's a vendor who solves problems for clients. The vendor produces an architecture document that describes how technology will achieve a solution †. There is no noping the fuck out, as this is a hospital a…

> Or an electoral district asking you to merge three emergency response systems into one. Or Nokia asking you to tariff calls going through a switch in real time. I’m well aware of what it is. I’ve been on real time telecom stuff (your last example) and know for a fact that engineers nope the fuck out of these huge ass architecture documents that include stakeholders, change control, etc. Inevitably there is some kin…

The way to solve that is basically DevOps. DevOps being a solution to a business problem, it is implemented as an array of "features" of integrating teams that work together on a product. It's a multi headed hydra and it's not easy. But the end result is people communicating better, which is the only thing that can really address a developer noping the fuck out. There is no technical thing, no document, no policy, etc that can fix it, as far as I'm aware.

Re: Architecture.md

#127

Post by matklad »

AnonC wrote: post #108

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?

> A picture can tell a thousand words

FWIW, this is generally false: https://graydon2.dreamwidth.org/193447.html

Re: Architecture.md

#128

Post by matklad »

mike31fr wrote: post #63

The author: "Keep it short" Also the author: "A good example of ARCHITECTURE document is the one from rust-analyzer" => redirects to an architecture file that takes 32 whole smartphone screen scrolls to read

That’s a fair observation! In my defense, rust-analyzer is a deep and complex project, so there’s a lot of stuff to describe. It’s closer to the 200k end.

Re: Architecture.md

#129

Post by avodonosov »

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…

I also use such hierarchical style, with lower level REAODMEs refferring iddividual source files. So that user continues from READMEs to code comments.

Example: https://github.com/cl-test-grid/cl-test-grid#system-architec...

On every level I first explain the task solved by this module and then go into the implementation details. Knowing the purpose first helps reader to understand impl details.

Re: Architecture.md

#130

Post by varajelle »

The othe document one should put next to README and CONTRIBUTING is CHANGELOG.

Way too often I find this document missing. Especially in the rust ecosystem: I see some crate bumped their version number, but no info about what changed. (And no, a git log is not a good substitute)

Post reply on HN