alunduil / alunduil/zfs-replicate

An ADR records which documentation framework docs/ follows

Aberta
#678 0 comentários 0 reações 0 responsáveis Ver no GitHub
enhancement
Linguagem predominante
Python
Estrelas
24
Forks
6
Merge médio
3h 11min
PRs com merge (30d)
49

Descrição

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

Guia de contribuição

Abrir o guia de contribuição

Direção de pesquisa

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.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Domínio
documentation
Tipo de issue
Documentação
Dificuldade
4/5
Tempo estimado
3-5 dias
Status de atividade
Ativa
Clareza
Razoavelmente clara
Facilidade para iniciantes
48/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.