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

41–50 of 159 posts

Re: Architecture.md

#41

Post by orthoxerox »

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…

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

Re: Architecture.md

#42

Post by matheusmoreira »

This is so useful. Even a simple description of the source code tree helps a lot. Otherwise people will have to find entry point files and recursively search the entire repository until they find what they're looking for.

Re: Architecture.md

#43

Post by ralmeida »

steveklabnik wrote: post #37
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…

I like this idea a lot, but you will cause a lot of people to bounce at step 2. Or at least, that has been my experience over the years. No matter how much you reassure them that it is okay if stuff is confusing and in fact you'd like to know about it so you can fix it, they'll say "great" and then go radio silent 99% of the time.

Sounds right to me too. One quicker way to improve the 'first process' is to change only step one - do not spend a long time, but instead write a few paragraphs with what's most important and/or top-of-mind. Often, this opens the door to more contributions and questions.

Of course, update accordingly whenever you find yourself in a discussion about something with a contributor (no matter if the architecture doc is even part of the discussion or not).

Re: Architecture.md

#45

Post by dognotdog »

steveklabnik wrote: post #37
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…

I like this idea a lot, but you will cause a lot of people to bounce at step 2. Or at least, that has been my experience over the years. No matter how much you reassure them that it is okay if stuff is confusing and in fact you'd like to know about it so you can fix it, they'll say "great" and then go radio silent 99% of the time.

I feel like for any long-running project, that person is at least ME. If I haven't written down some architectural information for complex projects, when I revisit a project after it being dormant for half year, I need to poke around to figure things out again.

If I have written down architecture notes in the first place, they are very helpful at this point; and if I haven't, it's a good time to start because I'll be acutely aware of the non-obvious parts as I re-familiarize myself with the code.

Re: Architecture.md

#46

Post by kortilla »

Spearchucker wrote: post #36
mholt wrote: post #2

Ah, we actually have one of these at Caddy: https://caddyserver.com/docs/architecture (The filename on disk is literally "architecture.md" -- it is a Markdown file rendered by Caddy's template handler: https://github.com/caddyserver/website/blob/master/src/docs/... ) It could use some improvement, but it's been really great for helping people learn how Caddy 2 works at a high level. Beyond our docs, I always encourag…

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…

How do you distill down critical outcomes of the architecture for people considering using your project? Based on my experience so far, engineers will look at a giant document, see phrases like “stakeholder management” and nope the fuck out.

What I want to know is, what are the key performance considerations, failure modes, recovery procedures, etc.

Re: Architecture.md

#47

Post by baby »

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]:

  consensus
  ├── src
  │   ├── block_storage          # In-memory storage of blocks and related data structures
  │   ├── consensusdb            # Database interaction to persist consensus data for safety and liveness
  │   ├── liveness               # RoundState, proposer, and other liveness related code
  │   └── test_utils             # Mock implementations that are used for testing only
  └── consensus-types            # Consensus data types (i.e. quorum certificates)
  └── safety-rules               # Safety (voting) rules
I recently digged into dependabot's code, and I found it extremely well structured. For example you have an Architecture section in the first README[2] with a diagram (how awesome is that!) and with links to the README of all the sub components, which themselves live in the subfolders[3].

What I dread the most is going through a new codebase and not seeing any documentation in internal packages. Like how the fuck am I supposed to understand anything in there? By reading all the code?

[1]: https://github.com/diem/diem/tree/master/consensus#how-is-th...

[2]: https://github.com/dependabot/dependabot-core#architecture

[3]: https://github.com/dependabot/dependabot-core/blob/main/comm...

Re: Architecture.md

#48

Post by Ma8ee »

kenniskrag wrote: post #20
exabrial wrote: post #17

So one thing we've done is write all of our applications the exact same way with well defined terms (on a wiki) and a commitment to no more than 4 layers. * Initiators (things that receive, decode, and validate input) * Controllers (Business logic containers. One function refers to one business action) * Services (Used by controllers to effectuate commands. Services absolutely cannot call other services) * Cross Cutt…

Why shouldn't a service call other services? One Service may extend the features e.g. network < encryption < http.

I don’t think the comment implies that a service can’t be layered.

Re: Architecture.md

#49

Post by petepete »

harikb wrote: post #33
arminiusreturns wrote: post #14

Earlier quoted context omitted.

I tend to prefer diagrams as code, so yoi can just embed an image that be updated, version controlled, etc, instead of ascii diagrams. Any reason in particular you want ascii instead of images?

Can you describe what 'diagrams as code' mean? I don't mind images, just wondering if Github would make it easier to generate those. Something like the syntax of web-sequence/uml but not limited to data-flows and something more simpler, ideally.

There are a few tools for creating diagrams with text, Asciiflow and Monodraw probably being the most popular.

* http://asciiflow.com/

* https://monodraw.helftone.com/

From my experience, you don't want to add anything too complicated or anything that's volatile to code, but in some cases a high level overview of how bits of an application fit together can be handy. These days it might be a better idea to just embed or reference a PlantUML diagram instead.

* https://plantuml.com/

Re: Architecture.md

#50

Post by FourthProtocol »

kortilla wrote: post #46
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…

How do you distill down critical outcomes of the architecture for people considering using your project? Based on my experience so far, engineers will look at a giant document, see phrases like “stakeholder management” and nope the fuck out. What I want to know is, what are the key performance considerations, failure modes, recovery procedures, etc.

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 asking you for a one-off to manage/settle insurance payments. 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.

† This is nuanced. Often a client's procurement department invites a number of candidate vendors to submit proposals including a design proposal/architecture and associated cost estimates. Vendors range from the high end (McKinsey, Bain & Co, Ernst & Young) to the mid-tier (Wipro, Accenture and so on) to the niche.

Post reply on HN