Convenciones¶

Reglas cortas para que el sitio no se vuelva un cajón de páginas sueltas.

El nav en mkdocs.yml es la fuente de verdad del menú. Si no está ahí, no aparece.
Las tablas de index.md de cada sección se actualizan en el mismo PR que crea o mueve la página.
El build --strict falla si un link o un ítem de nav apunta a un archivo inexistente. Eso es deseable.

Nombres de archivo¶

Minúsculas, guiones, sin acentos: alta-de-cliente.md, no Alta de Cliente.md.
Un tema por archivo.
El índice de cada carpeta se llama index.md.

Títulos¶

Un solo # por página (el H1).
El H1 coincide con lo que va en nav.
Usá ## para secciones y ### para subpasos.

Metadatos y tags¶

Al inicio de procesos, runbooks y páginas de guía relevantes:

---
title: Nombre visible
tags:
  - area
  - tipo
---

Taxonomía corta (elegí lo que aplique):

Familia	Valores típicos
area	`comercial`, `operaciones`, `infra`, `marketing`, …
tipo	`proceso`, `runbook`, `infra`, `guia`
plantilla	`plantilla` (solo en archivos de `guia/plantillas/`)

No inventes tags sueltos: si falta uno, sumalo acá en el mismo PR.

Estado y revisión¶

En el cuerpo de la página (bajo el H1):

Estado: borrador | activo | obsoleto
Última revisión: fecha ISO (YYYY-MM-DD)

Cadencia sugerida:

Tipo	Revisar al menos
Proceso	cada 6 meses o cuando cambie el flujo
Runbook	después de cada incidente que lo use, o cada 3 meses
Infra / guía	cuando cambie el sistema documentado

Si está obsoleto, dejá un link a la página que lo reemplaza y sacalo del nav (o movelo a una sección de archivo si hace falta).

Voz¶

Español rioplatense, voseo (configurá, ejecutá).
Imperativo para procedimientos.
Si un comando es destructivo, ponelo en !!! danger.

Secretos¶

No pegues contraseñas, tokens ni claves SSH en Markdown.

Escribí dónde vive el secreto (Coolify env, vault, 1Password) y quién lo rota. Nunca el valor.

Plantillas¶

Las plantillas viven en guia/plantillas/:

cp docs/guia/plantillas/proceso.md docs/procesos/mi-proceso.md
cp docs/guia/plantillas/runbook.md docs/runbooks/mi-incidente.md

No copies plantillas dentro de procesos/ o runbooks/ como si fueran docs reales: el índice de cada carpeta solo lista documentos publicados.

Plantilla mínima de proceso¶

# Nombre del proceso

**Dueño:** área o persona
**Sistemas:** lista
**Frecuencia:** diaria / semanal / a demanda
**Estado:** borrador | activo | obsoleto
**Última revisión:** YYYY-MM-DD

## Objetivo
## Alcance
## Pasos
## Errores frecuentes
## Relacionado

Plantilla mínima de runbook¶

# Nombre del incidente

**Severidad:** P1 / P2 / P3
**Síntoma:** qué se ve
**Impacto:** a quién afecta
**Estado:** borrador | activo | obsoleto
**Última revisión:** YYYY-MM-DD

## Diagnóstico
## Mitigación
## Recuperación
## Postmortem

Diagrama cuando aporta¶

Usá Mermaid si el flujo tiene más de tres sistemas. Si es un solo comando, no hace falta diagrama.

Links¶

Preferí links relativos entre páginas de docs/:

Ver la [plantilla de runbook](plantillas/runbook.md).

Checklist de PR (página nueva)¶

Archivo en la carpeta correcta (procesos/, runbooks/, infraestructura/, guia/)
Entrada en nav de mkdocs.yml
Fila en el index.md de la sección (si aplica)
Tags + Estado + Última revisión
Sin secretos en el Markdown
Links relativos; mkdocs build --strict en local si podés