diff --git a/index.md b/index.md index 7b79501..e25c65e 100644 --- a/index.md +++ b/index.md @@ -1,5 +1,3 @@ - - # Architecture knowledge base Welcome 👋 to the architecture knowledge base of Commanded Ecosystem. @@ -7,20 +5,32 @@ You will find here all the Architecture Decision Records (ADR) of the project. ## Definition and purpose -> An Architectural Decision (AD) is a software design choice that addresses a functional or non-functional requirement that is architecturally significant. -> An Architectural Decision Record (ADR) captures a single AD, such as often done when writing personal notes or meeting minutes; the collection of ADRs created and maintained in a project constitutes its decision log. +> An Architectural Decision (AD) is a software design choice that addresses a +> functional or non-functional requirement that is architecturally significant. +> +> An Architectural Decision Record (ADR) captures a single AD, such as often +> done when writing personal notes or meeting minutes; the collection of ADRs +> created and maintained in a project constitutes its decision log. + +An ADR is immutable: only its status can change (i.e., become deprecated or +superseded). That way, you can become familiar with the whole project history +just by reading its decision log in chronological order. -An ADR is immutable: only its status can change (i.e., become deprecated or superseded). That way, you can become familiar with the whole project history just by reading its decision log in chronological order. Moreover, maintaining this documentation aims at: - 🚀 Improving and speeding up the onboarding of a new team member -- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael Nygard's famous article on ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html)) +- 🔭 Avoiding blind acceptance/reversal of a past decision (cf [Michael + Nygard's famous article on + ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html)) - 🤝 Formalizing the decision process of the team ## Usage -This website is automatically updated after a change on the `main` branch of the project's Git repository. -In fact, the developers manage this documentation directly with markdown files located next to their code, so it is more convenient for them to keep it up-to-date. +This website is automatically updated after a change on [the `main` branch of +the Git repository](https://github.com/commanded/adr). In fact, the developers +manage this documentation directly with markdown files located next to their +code, so it is more convenient for them to keep it up-to-date. + You can browse the ADRs by using the left menu or the search bar. The typical workflow of an ADR is the following: @@ -29,6 +39,22 @@ The typical workflow of an ADR is the following: The decision process is entirely collaborative and backed by pull requests. +### Pro-tip + +Before proposing an ADR, it's a good idea to do the following: + +- Search for existing, related ADRs to make sure you aren't proposing something + that has already been proposed. + +- Search through [the + discussions](https://github.com/commanded/adr/discussions) to see if anyone + else is already thinking of similar ideas and you could join them in + championing an ADR. + +- Start a new discussion in the "Ideas" category to do some initial + information-gathering and determine the likelihood of your proposal being + accepted. + ## More information - [Log4brains documentation](https://github.com/thomvaill/log4brains/tree/develop#readme)