alunduil / alunduil/zfs-replicate
An ADR records which documentation framework docs/ follows
- 主要語言
- Python
- 星號
- 24
- 分支
- 6
- 平均合併
- 3 小時 11 分鐘
- 30 天內合併 PR
- 49
描述
## User story
As a **contributor adding a document**, I want **the project to state which framework `docs/` follows**, so that **I can tell where a new page belongs, and a reviewer can say a page is in the wrong place without arguing from directory names**.
## Current workaround
`docs/` carries `how-to/`, `reference/`, and `adr/`. Those names imply Diátaxis, but no file in the repo names it, adopts it, or says what the project takes from it. The framework is inferred from three directory names and nothing else.
That inference is already load-bearing. #677 argues `docs/reference/testing.md` sits in the wrong mode, and every step of that argument leans on what Diátaxis says reference material is. Without a recorded decision, the argument is one contributor's reading of an external site.
The unresolved parts are the ones that bite:
- Whether the framework covers contributor documentation, or only what a user of zfs-replicate reads. `docs/` today holds two user-facing how-to guides and one contributor-facing reference page.
- Whether `tutorials/` and `explanation/` are absent by decision or by accident.
- Where ADRs sit, given Diátaxis has no fourth mode for them.
## Alternatives considered
- Adopt Diátaxis explicitly, and record what it does and doesn't govern here.
- Adopt it for user documentation only, and say where contributor conventions live instead.
- Record that the directory names are convenience rather than a framework, which frees `docs/` from the four modes and makes #677 a plain placement question.
## Acceptance criteria draft
- [ ] An ADR states the framework, or states that none is adopted, with the reasoning.
- [ ] It says whether contributor-facing documentation belongs under `docs/`.
- [ ] It says where ADRs sit relative to the framework.
- [ ] #677 can cite it rather than citing diataxis.fr.
## Additional context
- #677 re-evaluates `docs/reference/testing.md` against Diátaxis and needs this vocabulary settled.
- [Diátaxis](https://diataxis.fr)
貢獻指南
研究方向
Start by reading the current docs/ layout, especially how-to/, reference/, and adr/, then review #677 to understand which placement question the decision must resolve. Record an ADR that addresses the listed acceptance criteria, including whether Diátaxis applies to contributor documentation and where ADRs belong, so #677 can cite the decision instead of the external framework site.
由索引模型根據 Issue 內容生成。
評估
- 領域
- documentation
- Issue 類型
- 文件
- 難度
- 4/5
- 預估耗時
- 3-5 天
- 活躍度
- 活躍
- 描述清晰度
- 基本清楚
- 新手友好度
- 48/100