Pros & Cons Architectural Decision (ADR) Markdown Table Template
A pros-and-cons table is the heart of an Architecture Decision Record: it shows which options were considered for a design question and why one won. Reviewers read it before approving the decision, and engineers read it a year later when they wonder why the system was built this way. In both cases the reader needs the rejected options and their reasons as much as the chosen one.
Edit This Template
Edit cells, add rows, or sort — the Markdown updates livePaste cells from Excel or Google Sheets into the first header to replace the table · Tab / Enter / arrows move · Shift+F10 opens row & column actions
When to Use This Table
Pros and cons only mean something relative to the decision drivers stated in the ADR’s context section — for example “user files must never leave the browser” or “must handle 200 MB inputs”. A pro that does not serve a driver is decoration, and a con that violates a hard constraint should disqualify the option outright rather than sit in a bullet list. Write the drivers first, then evaluate every option against the same ones.
The difference between an honest table and a rationalisation is symmetry and specificity. Every option is assessed on the same criteria; claims are quantified or testable (“adds roughly 2 MB to first load”) rather than adjectives (“heavier”); and the losing options are described well enough that their advocates would recognise them. Include the status quo or “do nothing” as an option whenever it is viable.
What Goes in Each Column
| Column | Alignment | What to put here |
|---|---|---|
| Evaluated Approach | left :--- | A short, distinctive name for each option, bolded, using the same wording as the ADR prose so readers can cross-reference. Mark the chosen option in the name or let the Final Decision column carry it — not both inconsistently. |
| Advantages (Pros) | left :--- | Two or three bullets tied to decision drivers, separated with <br> and a • character because GFM cells cannot hold real Markdown lists. Prefer measured claims (“no network upload”) over absolutes like “instant” or “zero latency”. |
| Tradeoffs (Cons) | left :--- | The costs, including ones paid later: operational burden, migration effort, vendor lock-in, hiring difficulty. State thresholds where they exist (“degrades above 50 MB on 4 GB devices”) so the con can be checked later. |
| Final Decision | center :---: | A fixed vocabulary, centered and bolded for the winner: Adopted, Rejected, or Deferred. A deferred option should name what would reopen it — a date, a metric, or an event — otherwise “deferred” is a polite rejection. |
How to Fill It In
- 1Write three to six decision drivers before listing options. Each should be testable: a cost ceiling, a latency budget, a compliance requirement, a team-skill constraint.
- 2List the options, including the current state of affairs if it is viable. If you cannot find a credible second option, the decision may not need an ADR at all.
- 3Gather evidence for each option: a time-boxed spike, a benchmark, vendor documentation, or a pricing calculation. Link sources in the ADR body rather than packing them into cells.
- 4Fill in pros and cons driver by driver. Then read the table column-wise: if privacy appears as a pro for one option, every other option’s row should say how it handles privacy.
- 5Ask someone who preferred a losing option to review its row. When they agree it is described fairly, record the decision, the date, and the ADR status (Proposed, Accepted, later Superseded).
Ready-to-Paste Variations
Weighted decision matrix
Use when there are several drivers of different importance. Score each option 1–5 per driver; the weighted total is a conversation starter, not an automatic verdict.
| Driver | Weight | Client-side | Server API | WASM Worker |
| :--- | ---: | ---: | ---: | ---: |
| Data stays on device | 5 | 5 | 1 | 5 |
| Handles 200 MB files | 3 | 2 | 5 | 4 |
| Infrastructure cost | 2 | 5 | 2 | 5 |
| First-load size | 2 | 5 | 5 | 2 |
| **Weighted total** | | **51** | **36** | **51** |Drivers as rows, options as columns
A transposed layout that makes asymmetric evaluation impossible to hide: every option must answer every driver.
| Driver | Client-side | Server API | WASM Worker |
| :--- | :--- | :--- | :--- |
| Privacy | Files never leave the browser | Uploads require a DPA and retention policy | Files never leave the browser |
| Large inputs | Limited by tab memory | Streams multi-GB files | Better memory control than JS |
| Ops burden | Static hosting only | API servers, scaling, on-call | Static hosting plus a build toolchain |Compact MADR-style options list
Mirrors the “Pros and Cons of the Options” section of the MADR template in a single table, for short ADRs.
| Option | Good, because | Bad, because | Outcome |
| :--- | :--- | :--- | :---: |
| PostgreSQL full-text search | No new service to run | Weak relevance tuning | **Chosen** |
| Dedicated search engine | Faceting and typo tolerance | Another cluster to operate and sync | Rejected |
| Do nothing (SQL `LIKE`) | Zero effort | Full table scans beyond ~1M rows | Rejected |Common Mistakes
Including a straw-man alternative that nobody would choose, so the preferred option looks good by comparison.
Only list options someone on the team would seriously defend, and have that person review the row. If there is no serious alternative, say so in the ADR context.
Listing different criteria for each option — performance for one, cost for another — so they cannot be compared.
Evaluate each option against the same drivers. The transposed variation above forces this by making drivers the rows.
Absolute marketing claims such as “100% secure”, “instant”, or “infinitely scalable”.
Replace each with a measurable statement and its condition, for example “no server round-trip; parse time under 200 ms for 5 MB on a mid-range laptop”.
Editing an accepted ADR’s table when circumstances change, which erases the reasoning that was valid at the time.
Write a new ADR that supersedes the old one and link them both ways. The old table remains an accurate record of what was known then.
Related Markdown Table Templates
Browse all 50 templatesEngineering Onboarding & Access Checklist
Structured onboarding milestone checklist for new software engineers covering hardware setup, repo permissions, local dev, and first deploy.
Project Architecture & Tech Stack
List technologies, libraries, packages, and cloud services powering your application by architectural tier.
Company & Team Quarterly OKRs Matrix
Objectives & Key Results governance table tracking strategic focus, baseline metrics, quarterly goals, confidence ratings, and leads.
Pros & Cons Architectural Decision (ADR): Frequently Asked Questions
What is an Architecture Decision Record?
An ADR is a short document capturing one significant design decision: the context and forces, the decision, and its consequences. Michael Nygard’s widely used format has sections for title, status, context, decision, and consequences; a pros-and-cons table usually supports the decision section.
How do I put bullet points inside a Markdown table cell?
GFM table cells hold a single line of inline content, so real Markdown lists are not possible. Use a bullet character such as • at the start of each item and separate items with <br>, which GitHub and GitLab render as a line break.
Where should ADRs live?
Most teams keep them in the repository, for example docs/adr/0007-client-side-parsing.md, numbered sequentially and reviewed through pull requests. Keeping them beside the code means the decision is versioned with the system it describes.
Should I use a weighted score instead of pros and cons?
A weighted matrix helps when there are many drivers of uneven importance, but the weights are judgement calls and can be tuned to produce any winner. Show the pros and cons as well, so readers can see the reasoning and not just a number.