api.fabaccess-api/docs/decisions/0000-use-markdown-architectural-decision-records.md

Use Markdown Architectural Decision Records (MADR)

Context and Problem Statement

We want to record architectural decisions made in this project. Which format and structure should these records follow?

Considered Options

• Markdown Architectural Decisions Record (MADR)
• Gitlab issues
• Formless – No conventions for file format and structure

Decision Outcome

Chosen option: "Markdown Architectural Decisions Record (MADR)", because

• Markdown is an easy to write textual format requiring no tooling to be easily human readable
• Markdown is widely supported and is auto-rendered by all git hosting platforms considered
• Can be easily stored alongside the actual code and documentation since plain-text files play well with git
• Is not bound to a single hosting platform like Gitlab issues would be
• Gives a very sensible default template and format for us to use