From 4143133ba13c6d07ccfd7df351ca2a7ce195b4df Mon Sep 17 00:00:00 2001 From: Kyle San Clemente Date: Thu, 20 Mar 2025 08:52:56 -0700 Subject: [PATCH 1/2] Create Proposal Doc --- ...-markdown-and-github-for-tech-proposals.md | 43 +++++++++++++++++++ ...markdown-architectural-decision-records.md | 26 ----------- 2 files changed, 43 insertions(+), 26 deletions(-) create mode 100644 decisions/0000-use-markdown-and-github-for-tech-proposals.md delete mode 100644 decisions/0000-use-markdown-architectural-decision-records.md diff --git a/decisions/0000-use-markdown-and-github-for-tech-proposals.md b/decisions/0000-use-markdown-and-github-for-tech-proposals.md new file mode 100644 index 0000000..8a30457 --- /dev/null +++ b/decisions/0000-use-markdown-and-github-for-tech-proposals.md @@ -0,0 +1,43 @@ +# Store Technical Proposals in GitHub vs. Notion + +## Context and Problem Statement +We want to record technical decisions and proposals made across the entire engineering org, independent of whether decisions concern the architecture, the code, or developer experience. +Should we store technical proposals in GitHub using MADR, or continue using Notion? + +## Considered Options +- GitHub (using MADR) +- Notion (current system) + +## Pros and Cons of the Options + +### GitHub (using MADR) + +#### Pros: +- PR Reviews on Technical Proposals +- GitHub is comfortable for engineers to use +- Markdown rocks! +- MADR allows for structured capturing of any decision. +- The MADR format is lean and fits our development style. +- The MADR structure is comprehensible and facilitates usage & maintenance. +- Version control and history tracking. + +#### Cons: +- Changes things +- Requires some kind of integration with notion to give product access +- Potential overhead of setting up and managing a new repository. +- Limited access/visibility for non-engineers without GitHub accounts. + +### Notion + +#### Pros +- Requires no change +- Everyone can access it +- Familiar interface and workflow for all employees. + +#### Cons +- Makes it hard to track feedback and changes on a technical proposal +- Less structured format compared to MADR. +- Lack of version control and history tracking in the same way as GitHub. + +## Decision Outcome +Chosen option: "", because diff --git a/decisions/0000-use-markdown-architectural-decision-records.md b/decisions/0000-use-markdown-architectural-decision-records.md deleted file mode 100644 index d7c7b10..0000000 --- a/decisions/0000-use-markdown-architectural-decision-records.md +++ /dev/null @@ -1,26 +0,0 @@ -# Use Markdown Architectural Decision Records - -## Context and Problem Statement - -We want to record architectural decisions made in this project independent whether decisions concern the architecture ("architectural decision record"), the code, or other fields. -Which format and structure should these records follow? - -## Considered Options - -* [MADR](https://adr.github.io/madr/) 4.0.0 – The Markdown Architectural Decision Records -* [Michael Nygard's template](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions) – The first incarnation of the term "ADR" -* [Sustainable Architectural Decisions](https://www.infoq.com/articles/sustainable-architectural-design-decisions) – The Y-Statements -* Other templates listed at -* Formless – No conventions for file format and structure - -## Decision Outcome - -Chosen option: "MADR 4.0.0", because - -* Implicit assumptions should be made explicit. - Design documentation is important to enable people understanding the decisions later on. - See also ["A rational design process: How and why to fake it"](https://doi.org/10.1109/TSE.1986.6312940). -* MADR allows for structured capturing of any decision. -* The MADR format is lean and fits our development style. -* The MADR structure is comprehensible and facilitates usage & maintenance. -* The MADR project is vivid. From 00ac59f31d01fa9798883ba3b4bf5b74ea6d9534 Mon Sep 17 00:00:00 2001 From: Kyle San Clemente Date: Thu, 20 Mar 2025 09:27:56 -0700 Subject: [PATCH 2/2] Update Proposal --- decisions/0000-use-markdown-and-github-for-tech-proposals.md | 1 + 1 file changed, 1 insertion(+) diff --git a/decisions/0000-use-markdown-and-github-for-tech-proposals.md b/decisions/0000-use-markdown-and-github-for-tech-proposals.md index 8a30457..4486771 100644 --- a/decisions/0000-use-markdown-and-github-for-tech-proposals.md +++ b/decisions/0000-use-markdown-and-github-for-tech-proposals.md @@ -20,6 +20,7 @@ Should we store technical proposals in GitHub using MADR, or continue using Noti - The MADR format is lean and fits our development style. - The MADR structure is comprehensible and facilitates usage & maintenance. - Version control and history tracking. +- We can use the repo to store standardized code like ci-config files #### Cons: - Changes things