alunduil / alunduil/zfs-replicate

An ADR records which documentation framework docs/ follows

Ouverte
#678 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
enhancement
Langage dominant
Python
Étoiles
24
Forks
6
Merge moyen
3 h 11 min
PR mergées (30 j)
49

Description

## 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)

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.