Technical Documentation Chaos: Keep Decisions in Nodes

Technical Documentation Chaos: Keep Decisions in Nodes

Six months ago, a decision was made not to migrate from PostgreSQL to MongoDB. Why? Who made the decision? What alternatives were evaluated? Why was Redis eliminated?

The answers to these questions exist somewhere. Maybe in a half-finished page in Confluence, maybe in a Notion document nobody has updated, maybe in the Slack thread from that meeting. A newly joined developer asks this question, nobody can give a complete answer. "We've always done it this way" gets said.

Technical decisions getting lost affects product quality. The same debates get reopened, rejected solutions get tried again, changes made without context unknowingly break previous decisions.

Why Technical Notes Get Scattered

Technical documentation fragmentation has its own dynamic. It starts with good intentions but can't be sustained.

Tool multiplicity kills the standard. There's Confluence, Notion, GitHub wiki, README. Every developer writes in a different place. Without a standard, there's no single place to search. "Where did I write that?" turns into "I didn't write it."

Decisions don't get written at the moment they're made. "I'll document it later" usually means it never gets documented. Right after leaving the meeting the context is still fresh; two days later the details are gone. Two weeks later, why that decision was made isn't remembered.

No format, no depth. "We chose Redis" isn't a decision record. Which alternatives did we evaluate, why did we choose Redis, what constraints steered us there, what were the trade-offs — without these written down, the decision is half-finished.

No connection. The decision sits in one place, the related task is somewhere else. When there's no bridge between them, the question "why did we write this code this way?" can't be answered.

What Is a Decision Record?

The approach known in software engineering as ADR (Architecture Decision Record) is based on a simple idea: every important technical decision should be recorded in a structured format.

The traditional form of an ADR is document-heavy and enterprise-oriented. For startups, this format is too heavy. But the core idea is valuable: decisions should be recorded at the moment they're made, together with their context.

In Alios, this idea gets moved into node descriptions. No separate tool, no separate system — decisions live in the same place where tasks live.

The Decision Node Format in Alios

A separate node is opened for each technical decision. This node isn't a task — it's a record. It doesn't get closed; it gets archived.

📌 DECISION — [Short title of the topic]
Status: Active / Revised / Superseded
Date: [Decision date]
Decision Makers: [Names or roles]

─────────────────────────────

🔍 CONTEXT
[Why did this decision become necessary? What problem
or requirement triggered it? 2-3 sentences.
Should be understandable to a non-technical reader.]

⚖️ OPTIONS EVALUATED

Option A: [Name]
Pros: [Items]
Cons: [Items]

Option B: [Name]
Pros: [Items]
Cons: [Items]

Option C: [Name — with reason for elimination]
Why eliminated: [1-2 sentences]

✅ DECISION MADE
[Which option was chosen — one sentence]

Rationale:
[Why this option? What constraints, priorities, or
trade-offs shaped this decision? 3-5 sentences.
This section is the most critical — a decision record
without rationale is incomplete.]

⚠️ ACCEPTED TRADE-OFFS
[What do we lose or what risk do we accept with this
decision? Should be written honestly.]

🔗 REFERENCES
[Related nodes, PRs, benchmarks, articles]

🔄 REVISION CONDITION
[When should this decision be reviewed?
Under what conditions should it change?]

Example: Database Selection Decision

The template filled in:

📌 DECISION — Primary Database Selection
Status: Active
Date: March 14, 2025
Decision Makers: CTO, Lead Backend Dev, Founder

─────────────────────────────

🔍 CONTEXT
A simple data model was sufficient for the MVP and
we used SQLite. When user count exceeded 500, query
times increased and concurrent write issues appeared.
Migration to a scalable database is needed. The team
also has strong SQL experience but limited NoSQL experience.

⚖️ OPTIONS EVALUATED

Option A: PostgreSQL
Pros: Strong SQL support, flexible schema with JSONB,
team has experience, open source, managed services available
Cons: Horizontal scaling is complex, no NoSQL flexibility

Option B: MongoDB
Pros: Flexible schema, easy horizontal scaling,
document model fits our current data structure
Cons: No team experience, transaction support not
as strong as PostgreSQL, high migration cost

Option C: MySQL
Why eliminated: Offers similar features to PostgreSQL
but JSON support is weaker. Since the team has PostgreSQL
experience, MySQL offers no advantage.

✅ DECISION MADE
PostgreSQL selected, managed service on Railway.

Rationale:
The team's existing SQL experience brings the learning
cost to zero. JSONB support provides schema flexibility
without needing to go full NoSQL. Managed service on
Railway reduces DevOps overhead. The current data model
is relational — PostgreSQL fits this structure better.
MongoDB's flexibility is an advantage we don't currently
need, losing its value against the learning cost.

⚠️ ACCEPTED TRADE-OFFS
Horizontal scaling may get complex later. If 10M+ records
are exceeded, sharding should be evaluated. We accept this
risk for now because reaching that scale first requires
resolving other bottlenecks.

🔗 REFERENCES
Node: "Database Migration Plan"
Node: "Railway Infrastructure Setup"
Benchmark: [Internal test results link]

🔄 REVISION CONDITION
This decision should be reviewed if active users exceed
50,000 or if average query time exceeds 500ms.

Search and Linking: Finding Decisions

Writing a decision record isn't enough — it needs to be findable. In Alios, there are two ways to do this.

Search: Search works across node titles and descriptions. Typing "PostgreSQL" lists all nodes containing that word. When a new developer wonders "why PostgreSQL?", they run a search and find the decision node.

This is why naturally using keywords in decision nodes matters. Technology names, topic headings, names of affected systems — when these appear in the description, they become searchable.

Linking: You add the decision node as a reference in the relevant task nodes. When a developer opens a database-related task, they see the line "related decision: Primary Database Selection" in the description. They click it, read the decision, start work with full context.

This linking habit gradually builds the team's knowledge graph. Decisions connect to tasks, tasks connect to epics, epics connect to goals.

Organizing Decision Nodes

Grouping all decision nodes under a single top-level node makes searching and navigation easier:

📁 TECHNICAL DECISIONS
├── 📌 DECISION — Primary Database Selection
├── 📌 DECISION — Frontend Framework Selection
├── 📌 DECISION — Authentication Approach
├── 📌 DECISION — Deployment Strategy
├── 📌 DECISION — API Versioning Standard
└── 📌 DECISION — Logging and Monitoring Infrastructure

This list becomes the central hub for the team's "why do we do it this way?" questions. One of the first things shown to new developers during onboarding.

Which Decisions Should Be Recorded?

Not every small technical preference needs a decision node. Decisions that meet these criteria should be recorded:

Ones that are costly to reverse — database selection, framework choice, API design. Ones that were debated — where there was disagreement on the team, where alternatives were evaluated. Ones that can't be understood without context — anything that will trigger the question "why did we do it this way?" Ones that constrain other decisions — situations where one decision creates constraints on other technical choices.

Small implementation details, code style preferences, and tool configurations don't need decision nodes — those belong in code comments or READMEs.

Final Thought

Technical documentation management stays on the "we'll do it later" list because its immediate value isn't visible. But six months later, when a new developer joins or an important architectural change is being discussed, the value of those records becomes clear.

Keeping decision nodes in the same system as tasks in Alios takes these records out of "a document sitting somewhere else." Decisions live inside the work, get linked to tasks, and can be searched.

The question "why did we make that decision?" no longer requires a meeting. The node is opened, and the answer is right there.