diff --git a/readme.md b/readme.md index 257038f..7317949 100644 --- a/readme.md +++ b/readme.md @@ -82,6 +82,24 @@ Elements in beautiful READMEs include, but are not limited to: images, screensho - [xnbox/DeepfakeHTTP](https://github.com/xnbox/DeepfakeHTTP#readme) - Original hero section. Clear navigation. Minimalist design. Appendices. - [zenml-io/zenml](https://github.com/zenml-io/zenml#readme) - Clean project logo. Useful TOC. Clear code examples amongst feature list. Quickstart example. +## Architecture Examples +A good ARCHITECTURE.md file helps developers understand how and where to make changes, whether they are new to a project or not. + +Diagrams, source code maps, and discussing invariants and design decisions is essential. + +This can also be a dedicated section of your README.md files. +- [Linux cryptography](https://github.com/torvalds/linux/blob/master/Documentation/crypto/architecture.rst) - Calls out different types of components, provides searchable areas, calls out invariants of different components, and describes structure with diagrams +- [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/wiki/Design) - Describes the initialization process, calls out environment requirements +- [Flutter engine](https://github.com/flutter/flutter/wiki/The-Engine-architecture) - Good use of high level diagrams to show the stack and it's parts. Describes the main processes. Describes platform invariants. +- [VSCode](https://github.com/microsoft/vscode/wiki/Source-Code-Organization) - Good use of high-level diagrams. Describes source organisation. +- [NextJS](https://github.com/vercel/next.js/blob/canary/docs/04-architecture/index.mdx) - Breaks architecture into separate files, calls out important dependencies. +- [rust-analyser](https://github.com/rust-lang/rust/blob/master/src/tools/rust-analyzer/docs/dev/architecture.md) - Good diagrams, describes entry points and source organisation, discusses architecture considerations. +- [Tauri](https://github.com/tauri-apps/tauri/blob/dev/ARCHITECTURE.md) - Well made source code map, discusses architecture considerations, calls out important dependencies. +- [NeoVim](https://github.com/neovim/neovim/blob/master/src/nvim/README.md) - Describes the main processes/lifecycle +- [GitLab](https://gitlab.com/gitlab-org/charts/gitlab/-/tree/master/doc/architecture) - Calls out design decisions +- [ESBuild](https://github.com/evanw/esbuild/blob/main/docs/architecture.md) - Great use of graphics for visualisations and project structure. Includes a list of important principles for the project. +- [Redis](https://github.com/redis/redis/blob/unstable/README.md) - Good source code map. Overviews of key files. Good use of documentation comments in-code rather than inline comments. + ## Articles @@ -91,6 +109,9 @@ Elements in beautiful READMEs include, but are not limited to: images, screensho - ["Readme Driven Development"](https://tom.preston-werner.com/2010/08/23/readme-driven-development.html) - *Tom Preston-Werner* - ["Top ten reasons why I won’t use your open source project"](https://changelog.com/posts/top-ten-reasons-why-i-wont-use-your-open-source-project) - *Adam Stacoviak* - ["What I learned from an old GitHub project that won 3,000 Stars in a Week"](https://www.freecodecamp.org/news/what-i-learned-from-an-old-github-project-that-won-3-000-stars-in-a-week-628349a5ee14/) - *KyuWoo Choi* +- *Architecture* + - ["ARCHITECTURE.md"](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html) - *Alex Kladov* + - ["Two open source projects with great documentation"](https://johnjago.com/great-docs/) - *John Jago* ## Tools