Add "Using in large projects" (#58)

adr · May 16, 2022 · d16899d · d16899d
1 parent 176fd41
commit d16899d
Show file tree

Hide file tree

Showing 2 changed files with 46 additions and 18 deletions.
diff --git a/docs/decisions/0010-support-categories.md b/docs/decisions/0010-support-categories.md
@@ -53,7 +53,7 @@ Use Angular ![category-frontend](https://img.shields.io/badge/category-frontend-
 * Good, because straight-forward to parse
 * Bad, because no simple filtering using `ls` or Windows Explorer is possible
 
-### Use YAML  frontmatter
+### Use YAML frontmatter
 
 Example:
 

diff --git a/docs/index.md b/docs/index.md
@@ -11,23 +11,25 @@ The template originated from capturing architectural decisions and developed to
 <!-- markdownlint-disable-file MD036-->
 **Note that this documentation describes MADR 3.0.0-alpha (not yet released) and might not apply to earlier released versions**
 
-- [News](#news)
-- [Overview](#overview)
-- [Example](#example)
-- [Apply it to your project](#apply-it-to-your-project)
-  - [Initialization](#initialization)
-  - [Create a new ADR](#create-a-new-adr)
-  - [Lint ADRs](#lint-adrs)
-- [License](#license)
+* [News](#news)
+* [Overview](#overview)
+* [Example](#example)
+* [Apply it to your project](#apply-it-to-your-project)
+  * [Initialization](#initialization)
+  * [Create a new ADR](#create-a-new-adr)
+  * [Lint ADRs](#lint-adrs)
+* [Using in large projects](#using-in-large-projects)
+  * [Usage of categories](#usage-of-categories)
+* [License](#license)
 
 ## News
 
-- 2021-04-25: MADR examples featured in Medium stories ["From Architectural Decisions to Design Decisions"](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and ["ADR = Any Decision Record?"](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) <!-- and blog post ["ADR = Any Decision Record? Architecture, Design and Beyond"](https://ozimmer.ch/practices/2021/04/23/AnyDecisionRecords.html) -->
-- 2021-04-08: MADR recommended as an ADR format in "Design Practice Repository". This ebook is available on [Leanpub](https://leanpub.com/dpr). The decision capturing activity is also described [online](https://socadk.github.io/design-practice-repository/activities/DPR-ArchitecturalDecisionCapturing.html).
-- 2020-09-29: MADR presented in the keynote "Markdown Architectural Decision Records: Capturing Decisions Where the Developer is Working" at the workshop "[Second Software Documentation Generation Challenge (DocGen2)](https://dysdoc.github.io/docgen2/index.html)". Slides available at [Speaker Deck](https://speakerdeck.com/koppor/markdown-architecturaldecisionrecords-capturing-decisions-where-the-developer-is-working).
-- 2019-07-08: MADR referenced in [Architectural Decisions — The Making Of](https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html), a post in the new blog "The Concerned Architect" by Olaf Zimmermann (shorter version available on [Medium](https://medium.com/@docsoc/y-statements-10eb07b5a177)).
-- 2018-04-13: Mentioned in [@vanto](https://github.com/vanto)'s presentation about ADRs: <https://speakerdeck.com/vanto/a-brief-introduction-to-architectural-decision-records>.
-- 2018-04-03: Scientific publication: [Markdown Architectural Decision Records: Format and Tool Support](http://ceur-ws.org/Vol-2072/paper9.pdf).
+* 2021-04-25: MADR examples featured in Medium stories ["From Architectural Decisions to Design Decisions"](https://medium.com/olzzio/from-architectural-decisions-to-design-decisions-f05f6d57032b) and ["ADR = Any Decision Record?"](https://medium.com/olzzio/adr-any-decision-record-916d1b64b28d) <!-- and blog post ["ADR = Any Decision Record? Architecture, Design and Beyond"](https://ozimmer.ch/practices/2021/04/23/AnyDecisionRecords.html) -->
+* 2021-04-08: MADR recommended as an ADR format in "Design Practice Repository". This ebook is available on [Leanpub](https://leanpub.com/dpr). The decision capturing activity is also described [online](https://socadk.github.io/design-practice-repository/activities/DPR-ArchitecturalDecisionCapturing.html).
+* 2020-09-29: MADR presented in the keynote "Markdown Architectural Decision Records: Capturing Decisions Where the Developer is Working" at the workshop "[Second Software Documentation Generation Challenge (DocGen2)](https://dysdoc.github.io/docgen2/index.html)". Slides available at [Speaker Deck](https://speakerdeck.com/koppor/markdown-architecturaldecisionrecords-capturing-decisions-where-the-developer-is-working).
+* 2019-07-08: MADR referenced in [Architectural Decisions — The Making Of](https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html), a post in the new blog "The Concerned Architect" by Olaf Zimmermann (shorter version available on [Medium](https://medium.com/@docsoc/y-statements-10eb07b5a177)).
+* 2018-04-13: Mentioned in [@vanto](https://github.com/vanto)'s presentation about ADRs: <https://speakerdeck.com/vanto/a-brief-introduction-to-architectural-decision-records>.
+* 2018-04-03: Scientific publication: [Markdown Architectural Decision Records: Format and Tool Support](http://ceur-ws.org/Vol-2072/paper9.pdf).
 
 ## Overview
 
@@ -110,9 +112,9 @@ As a consequence, some existing tooling might not be applicable.
 
 The filenames are following the pattern `NNNN-title-with-dashes.md` ([ADR-0005](docs/decisions/0005-use-dashes-in-filenames.md)), where
 
-- `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
-- the title is stored using dashes and lowercase, because [adr-tools] also does that.
-- the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
+* `NNNN` is a consecutive number and we assume that there won't be more than 9,999 ADRs in one repository.
+* the title is stored using dashes and lowercase, because [adr-tools] also does that.
+* the suffix is `.md`, because it is a [Markdown](https://github.github.com/gfm/) file.
 
 Decisions are placed in the subfolder `decisions/` to keep them close to the documentation but also separate the decisions from other documentation.
 
@@ -129,6 +131,32 @@ There is an initial configuration for it at `template/.markdownlint`.
 You can use that configuration in a GitHub workflow.
 See [`.github/workflows/lint.yaml`](.github/workflows/lint.yaml) for an example.
 
+## Using in large projects
+
+Large projects may have hunders decision records, where finding them might be hard.
+MADR does not enforce any repository or directory organization structure.
+In the following proposals from the community are presented
+
+### Usage of categories
+
+However, MADR leans forward to categorize ADRs using sub directories and put the ADRs into these sub folders.
+
+Example folder structure could be as follows:
+
+```tree
+.
+`-- decisions
+    |-- backend
+    |   |-- 0001-use-quarkus.md
+    `-- ui
+        `-- 0001-use-vuejs.md
+```
+
+With this approach, all categories are explicit, because the sub directories define the catories.
+It is accepted, that numbers of ADRs are not unique throughout the repository any more, but local for a category.
+
+Note that other alternatives are discussed at [ADR-0010](decisions/0010-support-categories.md).
+
 ## License
 
 This work is dual-licensed under [MIT](https://opensource.org/licenses/MIT) and