didericis/bot-bottle
1
0
Fork 0
Code Issues 7 Pull Requests 15 Actions Packages Projects Releases Wiki Activity

docs: hoist "when to write which document" to docs/README.md

Browse Source 
Move the document-type comparison out of docs/decisions/README.md
(where it only surfaced if you were already in the decisions dir) up
to a new docs/README.md, renamed "When to write which document".
Leave a pointer from the decisions README.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
didericis
2026-05-28 22:21:28 -04:00
parent 2141a85884
commit 1308e61c7e
2 changed files with 21 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+18
View File
@@ -0,0 +1,18 @@
# Docs
How this project records what it builds and why — and a guide to
picking the right document for what you're capturing.
## When to write which document
| Artifact | For |
|---|---|
| **PRD** (`docs/prds/`) | A feature: what to build, scope, success criteria. |
| **Research note** (`docs/research/`) | A landscape/tradeoff investigation. |
| **Decision record** (`docs/decisions/`) | A decision that isn't itself a feature — a policy, a convention, a "we will / won't do this," or a load-bearing choice made inside a larger PRD that deserves to be discoverable on its own. |
A decision that's fully specified by a PRD doesn't need duplicating in
a decision record. Write one when the *decision* would otherwise be
buried in prose, lost in an issue thread, or have no in-repo home at
all (small requests that don't merit a PRD; non-feature choices like
merge strategy or a trust posture).
docs/decisions/README.md
+3 -15
View File
@@ -7,21 +7,9 @@ reasoning lives in the clone, not in a forge issue thread or a chat log
that disappears when the provider does.
See `docs/research/issue-tracking-vs-in-repo-decision-history.md` for
the rationale behind keeping decision history in-repo.
## When to write one
| Artifact | For |
|---|---|
| **PRD** (`docs/prds/`) | A feature: what to build, scope, success criteria. |
| **Research note** (`docs/research/`) | A landscape/tradeoff investigation. |
| **Decision record** (`docs/decisions/`) | A decision that isn't itself a feature — a policy, a convention, a "we will / won't do this," or a load-bearing choice made inside a larger PRD that deserves to be discoverable on its own. |
A decision that's fully specified by a PRD doesn't need duplicating
here. Write a record when the *decision* would otherwise be buried in
prose, lost in an issue thread, or have no in-repo home at all (small
requests that don't merit a PRD; non-feature choices like merge
strategy or a trust posture).
the rationale behind keeping decision history in-repo, and
[`docs/README.md`](../README.md) for when to write a decision record
vs. a PRD or research note.
## Format