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..4486771 --- /dev/null +++ b/decisions/0000-use-markdown-and-github-for-tech-proposals.md @@ -0,0 +1,44 @@ +# 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. +- We can use the repo to store standardized code like ci-config files + +#### 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.