51–60 of 159 posts
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…
What happens past the 200k mark?
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.
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".
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.
Yes, that’s extra thick sarcasm.
I know I will sound another Rust evangelist, but people this person is the main maintainer of RA (Rust-analyzer), a LSP protocol implementation, anyone who tried RLS (Rust Language Server) then RA knows how great this tool helps you at learning and developing stuff with Rust. I use the nightly version (which updates everyday) and ohh boy... Never had the "opportunity" to caught a nasty bug or anything.
Also read his blog, it's a joy :)
Ty Matklad <3