LogoLogo
  • Technical Direction
  • Technical overview
    • Technical Implementation
    • API Design Guide
      • Data Definitions and Standards
      • Data Transfer Objects
      • Documentation
      • Environments
      • Error Handling
      • Example API Service
      • GraphQL Naming Conventions
      • Methods
      • Naming Conventions
      • Once Only Principle
      • Pagination
      • Resource Oriented Design
      • REST Request
      • REST Response
      • Security
      • Versioning
    • Ísland.is Public Web Data Flow
    • Code Reviews
    • Code Standards
    • Monorepo
    • Project Management
    • Teamwork
    • Architectural Decision Records
      • Use Markdown Architectural Decision Records
      • Use NX
      • Continuous Integration
      • CSS
      • Branching and Release Strategy
      • Error Tracking and Monitoring
      • What API Management Tool to Consider
      • Viskuausan Static Site Generator
      • Use OAuth 2.0 and OpenID Connect As Protocols for Authentication and Authorization
      • Unified Naming Strategy for Files and Directories
      • CMS
      • Open Source License
      • What Chart Library Should We Use Across Island.is?
      • What Feature Flag Service/application Should We Use at Island.is?
      • Logging, Monitoring and APM Platform
      • ADR Template
    • Log Management Policy
  • Products
    • Island.is Authentication Service
      • Terminology
      • Integration Options
      • Authentication Flows
      • Authorising API Endpoints
      • Session Lifecycle
      • Scopes and Tokens
      • Delegations
      • Configuration
      • Tools and Examples
      • Environments
      • Test IAS with Postman
    • Notifications / Hnipp
      • New Notification Setup Guide
      • Notifications service workflow overview
      • Email notifications
    • Pósthólfið
      • Security Checklist
      • Introduction
      • Skjalatilkynning API
      • Skjalaveita API
      • Sequence Diagram
      • Interfaces
    • Straumurinn (X-Road)
      • Architecture Guidelines for Service Providers and Consumers
      • Setting up an X-Road Security Server
        • Network Configuration
      • X-Road - Uppfærsla á öryggisþjónum
      • Straumurinn - Notkun og umsýsla
      • X-Road Central - current version
  • Development
    • Getting Started
    • Generating a New Project
    • Definition of done
    • Devops
      • Continuous Delivery
      • Database
      • Dockerizing
      • Environment Setup
      • Logging
      • Metrics
      • NextJS Custom Server
      • Observability
      • Operations Base Principles
      • Security
      • Service Configuration
      • Support
    • AWS Secrets
    • Feature Flags
    • Documentation Contributions
    • Defining Monorepo Boundaries With Tags
    • OpenAPI
    • Code Generation
    • Workspace Settings (Deprecated)
    • External Contributions
  • REFERENCE
    • Problems
      • 400 Validation Failed
      • 400 Attempt Failed
      • 403 Bad Subject
      • 400 500 Template API Error
    • Glossary
  • Misc
    • Guide: Adding a Payment Step to an Application
    • Guide: Enable Organisations to Make Requests to an Application
    • README Template
Powered by GitBook
On this page
  • Context and Problem Statement
  • Considered Options
  • Decision Outcome

Was this helpful?

  1. Technical overview
  2. Architectural Decision Records

Use Markdown Architectural Decision Records

PreviousArchitectural Decision RecordsNextUse NX

Last updated 1 year ago

Was this helpful?

  • Status: accepted

  • Deciders: devs, devops

  • Date: 01.06.2020

Context and Problem Statement

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

Considered Options

  • 2.1.0 - The Markdown Architectural Decision Records

  • - The first incarnation of the term "ADR"

  • - The Y-Statements

  • Other templates listed at

  • Formless - No conventions for file format and structure

Decision Outcome

Chosen option: "MADR 2.1.0", because

  • Implicit assumptions should be made explicit.

    Design documentation is important to enable people understanding the decisions later on.

    See also .

  • The MADR format is lean and fits our development style.

  • The MADR structure is comprehensible and facilitates usage & maintenance.

  • The MADR project is vivid.

  • Version 2.1.0 is the latest one available when starting to document ADRs.

MADR
Michael Nygard's template
Sustainable Architectural Decisions
https://github.com/joelparkerhenderson/architecture_decision_record
A rational design process: How and why to fake it