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

31–40 of 159 posts

Re: Architecture.md

#31

Post by matklad »

gorgoiler wrote: post #22

This is predictably unrelated but how can someone go to the effort of having such beautiful typeface selection and still have an unhyphenated ragged right? Great advice though, otherwise.

Yeah, I indeed spend some effort to steal the fonts from asciidoctor and https://www.teamten.com/lawrence/programming/ (highly recommend both).

And yes, I myself am struggling with ragged right. I really wish to have proper text hyphenation and justification, to have a book-like feel. Sadly, justification without hyphenation looks ugly, and `hyphens: auto` doesn’t work well (and wasn’t supported in chrome last time I checked).

I am pretty baffled that such basic (in terms of impact, not in terms of complexity of implementation) feature isn’t widely available.

Although I am not a web designer, so I might be missing some simple way to solve this.

Re: Architecture.md

#32

Post by matklad »

amw-zero wrote: post #7

How do you keep this up to date though? That's the biggest problem with documentation. Having some kind of append-only format, like ADR, can help, since the documentation specifically is tied to a decision at a single point in time. Still, those can drift from the actual implementation to the point where they are both misleading and confusing. Such is the entropic nature of software.

Revise it twice a year. If the document gets stale faster than that, just delete the stale bits: they are probably too low level for this kind of documentation.

Re: Architecture.md

#33

Post by harikb »

arminiusreturns wrote: post #14
harikb wrote: post #6

Any word on supporting diagrams inside GitHub flavored markdown?

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.

Re: Architecture.md

#34

Post by ausjke »

arminiusreturns wrote: post #14
harikb wrote: post #6

Any word on supporting diagrams inside GitHub flavored markdown?

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?

pure text is easy to work with most of the time, in fact ascii diagram is used heaviyl in RFCs

Re: Architecture.md

#35

Post by alixanderwang »

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 docs by including the synced repo as a submodule.

https://github.com/terrastruct-bot/Demo

Re: Architecture.md

#36

Post by Spearchucker »

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 these layers, and components within each layer. I do that for each tier.

After that maybe something about quality objectives and how they might be met, eg: availability (MTTF / (MTTF + MTTR) * 100), efficiency, flexibility, integrity, interop, usability and so on.

This leads to a physical delpoyment model, which shows layers deployed to tiers. And yes, I'm rather fond of Visio.

Then a bit about approach (dev/deployment and operational management) risk and stakeholder management, technical reviews (change control board maybe?), and project reviews.

To be fair I come from a predominantly critical systems world (telecoms OSS and BSS, healthcare, transport and some fintech. And in that world architecture is very far removed from actual code until eventually.

Re: Architecture.md

#37

Post by steveklabnik »

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.

Re: Architecture.md

#38

Post by simonw »

matklad wrote: post #32
amw-zero wrote: post #7

How do you keep this up to date though? That's the biggest problem with documentation. Having some kind of append-only format, like ADR, can help, since the documentation specifically is tied to a decision at a single point in time. Still, those can drift from the actual implementation to the point where they are both misleading and confusing. Such is the entropic nature of software.

Revise it twice a year. If the document gets stale faster than that, just delete the stale bits: they are probably too low level for this kind of documentation.

I find filing issues whenever I find out-of-date docs helps. They tend to get fixed pretty quickly, because they offer a nice change of pace from working on bugs or features.

Re: Architecture.md

#39

Post by NicoJuicy »

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…

Indeed, I was thinking about ADR's too

Re: Architecture.md

#40

Post by Terretta »

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://marketplace.visualstudio.com/items?itemName=bierner....

You can also edit and enjoy these markdown pages with diagrams on Mac, iPad, iPhone: https://www.mweb.im/

Lastly, if anyone is not sure what to diagram for readers of architecture.md, consider the C4 model:

https://c4model.com/

Post reply on HN