61–70 of 159 posts
[0] https://github.com/laurent22/joplin/tree/dev/readme/spec
I find it useful to include an architecture diagram in the README for small projects, and the best way is to use the VSCode DrawIO extension. You can directly edit .drawio.svg files and embed them into the README. You get live editing and up-to-date images at the same time!
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
> If you maintain an open-source project in the range of 10k-200k lines of code What happens past the 200k mark?
Realistically, past the 200k lines of code point you aren't dealing with a codebase anymore; you're an _organization_. You need knowledge management--where do architecture decisions live, how are they approved, how are they taught to new developers, how are they updated as maintainers come and go, etc. It takes strong engineering management and leadership to keep it together.
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…
This is one of the superpowers of Go: for most Go projects, this is exactly what I'd do. Just read the code. It's easy to follow, it's all formatted the same, very little implicit behavior, and I don't need an IDE to do it.
Few languages were designed to be read by others. Thankfully Go is one of them.
Along the lines of an ADR, another useful document to have is Decisions and Opinions. Often choices are subjective, highlighting these will let contributors know about your preferences for the project. Often these relate more to linting styles, choice of libraries, etc.
An interesting systemsy difference is that missing style.md means more work for maintainers (as they need to do more cleanup), while missing architecture.md means more work for contributors.
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…
Off topic - what is the theme used in Caddy doc site? looks super cool.
Earlier quoted context omitted.
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.
Oh, so the solution is to just add another thing to “remember” to do. That must be what I’ve been missing all these years. Yes, that’s extra thick sarcasm.
In practice, I personally didn’t find it difficult to maintain half-decent ARCHITECTURE.md, and I am not at all good with keeping the docs otherwise.
> If you maintain an open-source project in the range of 10k-200k lines of code What happens past the 200k mark?
Earlier quoted context omitted.
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 a…
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 kind of outage or botched upgrade with lots of finger pointing and then the vendor covers their ass by referencing “page 248 under heading ‘assumptions about bisectional bandwidth’” or some bullshit right before the section on ‘renegotiating requirements during a government declared emergency’.
There needs to be a better way because I assure you, the people using your system are (on average) barely going to skim your document.
Being a “very serious” industry does not change this. Look at the disaster that was Healthcare.gov. That had mountains of documents like you describe they overlooked the simple requirement of scaling identity lookups.