> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://naturgy-comer-documentation-p5mde.vercel.app/api/mcp` to find what you need.

# Estándar de documentación

Este estándar mantiene navegable la documentación para personas y agentes. Cada
página tiene una intención Diátaxis clara, un único propietario y una fuente de
autoridad identificable.

## Metadatos obligatorios

Toda página renderizada debe incluir:

* `description`: una frase que explique su valor;
* `docId`: identificador estable para máquinas;
* `domain`: dominio principal;
* `diataxis`: `tutorial`, `how-to`, `explanation` o `reference`;
* `scope`: área de propiedad y compatibilidad;
* `audience`: `public`, `internal` o `shared`;
* `kind`: función de la página;
* `status`: `canonical`, `generated`, `working` o `skeleton`;
* `keywords`: términos que un agente pueda buscar;
* `reviewedAt`: fecha de la última comprobación, cuando la página contiene
  datos temporales o generados.

Cuando una página contiene datos temporales, el cuerpo debe indicar fecha,
versión o alcance de la última lectura. No inventes fechas de revisión.

## Navegación por dominio

```text
/<dominio>
├── tutorials/    aprender un recorrido completo
├── how-to/       completar una tarea concreta
├── explanations/ entender contexto, diseño y decisiones
└── reference/    consultar contratos e inventarios
```

Los dominios actuales son `atc`, `super-app`, `operations`, `account`,
`method`, `agent-guide` y `reference`. Una sección puede quedar vacía o marcada
como `skeleton` si todavía no existe material respaldado por fuentes.

* **Tutoriales:** recorrido de aprendizaje completo y guiado.
* **Guías prácticas:** pasos para resolver una tarea conocida.
* **Explicaciones:** contexto, diseño, decisiones y relaciones.
* **Referencia:** contratos, inventarios y datos de consulta.

Si una página sirve a dos intenciones, elige un propietario y enlázala desde la
otra sección. No dupliques contenido para llenar una categoría.

## Audiencia

Las etiquetas `public`, `internal` y `shared` describen la audiencia prevista.
No crean ramas paralelas de navegación ni sustituyen una decisión de acceso.

## Índice de agentes

Mantén sincronizados el [índice de agentes](/reference/agent-index) y
`/agent-index.json`. El catálogo expone `domain`, `diataxis`, `audience`, `status`
y `keywords` para que un agente pueda filtrar sin inferirlos del título.

Las páginas generadas y de trabajo llevan el estado correspondiente y no se
presentan como documentación canónica estable.

## Cobertura de un caso de uso

Una documentación completa de caso de uso cubre:

1. resumen, audiencia y resultado;
2. contexto y alcance;
3. actores y sistemas;
4. flujo normal;
5. excepciones y recuperación;
6. datos, permisos y conservación;
7. responsables, estado y fechas de revisión;
8. referencias autorizadas.

## Reglas de calidad

* Mantén una preocupación principal por página.
* Define los acrónimos en su primera aparición y enlaza el [glosario](/reference/glossary).
* Explica supuestos y preguntas sin resolver.
* Conserva los estados **verificado**, **por confirmar** y **no encontrado**.
* No publiques credenciales, datos personales ni cargas confidenciales.
* Actualiza juntos los índices, la navegación, las redirecciones y el catálogo.
* Revisa la publicación con [Validar una publicación](/method/how-to/publish).