Mar 11, 20264 min read

Why Every Repo Should Have a docs/solutions Folder

A developer who joins the project six months from now does not need the changelog. They need to know why the decision was made and what almost went wrong.

docs/solutions/ is the simplest possible answer to that: a directory in the repository, versioned alongside the code, documenting what was learned rather than what was done.

The problem it solves

Every team carries tribal knowledge. "Why do we use LVM-thin here instead of ZFS?" — the engineer who made that call eight months ago knows. When they leave, the knowledge leaves with them.

Confluence and Notion capture project documentation, but they don't survive the context of the moment. There's no commit that produced the problem, no date the decision was made, no PR that implemented the fix.

The practical result: teams redo analyses that were already done, repeat the same mistakes in similar contexts, and onboard new members via "go ask so-and-so" — which does not scale.

The convention

Each file documents one solved problem or one blocker cleared. The minimum structure:

# [Descriptive title of the solved problem — not generic]

## Context
When this happens. Who hits it. What state the system is in.

## Problem
What was blocking. Why it wasn't trivial to solve.

## Solution
What worked. Exact commands where relevant.

## Why This Approach
Why this and not the obvious alternatives.
Alternatives considered, and why they were discarded.

## Prerequisites
What needs to be in place first.

Why not the alternatives

Confluence per project is fine for formal documentation but disconnected from the code. No commit↔doc traceability, and it drifts out of date because there's no friction stopping you from creating an inconsistent page.

GitHub/GitLab wikis live outside the main repository. They don't show up in a local grep, and there's no CI to validate them.

Code comments are readable in context but not searchable by problem, and they don't capture higher-order reasoning — the "why this approach" part.

docs/solutions/ wins because it sits in the repo: versioned with the code, searchable with rg, linkable from commits and tickets.

Four reasons it works

Versioned with the code. The commit that fixes the problem carries the documentation. Twelve months later, git log --all -- docs/solutions/X.md tells the whole story.
Linkable. A Refs: docs/solutions/blockers-report.md#B2 line in a commit message creates real traceability between a decision and its rationale.
Searchable. It's in the repo. It shows up in rg "LVM-thin", in GitHub search, in your editor's file switcher. No browser, no context switch.
It feeds the graph. Each file becomes a literature note in the Zettelkasten, so repository knowledge lands in permanent personal knowledge instead of staying trapped in one project.

What it costs

You gain dramatically faster onboarding, past decisions you can consult before redoing the work, and — as a side effect — blog posts that emerge naturally, since every solution file is already a draft.

You pay with discipline. The PR that fixes a problem also has to create the file. Without enforcement the convention degrades, and it risks becoming an unstructured troubleshooting log if nobody follows the template.

How it fails

It becomes a personal Stack Overflow. Files that are just command dumps with no reasoning. The diagnostic is simple: if ## Why This Approach is empty, it isn't a solution — it's a gist.

It goes stale. A file documents a workaround that was later fixed properly, but nobody updated it. Add a ## Status: superseded by X line when the approach changes.

Wrong granularity. One file per individual command is too fine; one file covering "all deploy problems" is too coarse. The heuristic: one problem in one specific context equals one file.

What I learned

The minimum template matters more than the perfect template. Five partially-filled sections beat an elaborate format nobody uses.

## Why This Approach is the most valuable section and the most skipped. Forcing it — even if the answer is only "because alternatives A and B failed for reason X" — is what separates documentation from archiving.

And name the files descriptively. windows-terminal-ssh-fragments.md is findable; solution-001.md requires an index nobody maintains.