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

Ask HN: Are there any openly available software architecture documents?

news.ycombinator.com

Post reply on HN
Print view View original

51–53 of 53 posts

Re: Ask HN: Are there any openly available software architecture documents?

#51

Post by lllr_finger »

NicoJuicy wrote: post #25

ADR is made for this https://github.com/joelparkerhenderson/architecture_decision... There are multiple variants. Simple or detailed.

ADRs are great, and don't need to be overly formal or use tooling. We've been hand-writing Markdown-based ADRs (https://github.com/adr/madr) checked in with our code in a docs/adr directory.

You don't put every little decision in of course, but most projects have at least 1-2 areas where even the people involved with the decision have a hard time recollecting all the context for the decision.

The downside, at least for OP, is that they're usually something you capture at the time the decision is made - not when you're leaving a project.

Re: Ask HN: Are there any openly available software architecture documents?

#52

Post by markmiro »

I think it's worth looking at it like another product that you produce. I like to imagine someone seeing my code for the first time and trying to make sense of it.

Architecture: this is often documented with some kind of diagram. I personally find them to be unhelpful.

Flow: I'm guessing people aren't familiar with your UI. The best way to document would be to record a video, but that might be a little extra. I would make a powerpoint doc with screenshots to show the common flows.

For me, it kinda looks like this:

- Assume expertise in the individual technologies you've used

- If you picked the tech, then write why you did, and link to resources to learn more about it

- Write down which general constraints I placed on myself that might not be common. EX: naming patterns, cyclomatic complexity, using a functional approach, or being more point-free in a language where it's not common, choices around duplicate code

- Make a nested list of the folder structure and describe what each folder is for (even if it feels obvious), and describe how the different parts interact with each other. The questions to answer are: what are the high-level dependencies between dirs? Are there any cyclical dependencies?

- Find the knots (especially complex parts of the codebase) and make sure they're documented properly

Post reply on HN