Saltar a contenido

Guía de Contribución a la Documentación

Principios

  • La documentación se organiza por Diátaxis: Tutoriales, Cómo hacerlo, Referencia, Explicaciones.
  • Cada página debe tener front-matter con title, summary, icon y tags.
  • El idioma base es español; usa títulos en Title Case breve y slugs en kebab-case.

Front-matter (obligatorio)

---
title: 'Título claro (<=60)'
summary: 'Resumen de 1–2 frases para SEO y navegación.'
icon: material/book-open-page-variant
tags:
    - categoria
    - subcategoria
---
  • El primer # H1 debe coincidir con title.
  • Usa icon de Material Icons (prefijo material/).

Estilo de escritura

  • Escribe en español neutro, directo y orientado a tareas.
  • Evita mezclar tipos de contenido: no pongas pasos en Referencia, ni API en Tutoriales.
  • Prefiere ejemplos completos y mínimos; añade enlaces a contexto cuando haga falta.

Snippets de código

  • Usa bloques con lenguaje: php, bash, tsx, ts, json, http, ini, sql.
  • Evita líneas muy largas; divide comandos en múltiples líneas cuando sea necesario.
  • Marca input/outputs y peligros con admonitions.

Admonitions y Tabs

  • Admonitions: !!! note|tip|warning|danger con títulos cortos.
  • Tabs de alternativas: pymdownx.tabbed con títulos claros (p. ej. Linux/Windows, npm/yarn).

Clasificación por Diátaxis

  • Tutoriales: primeros pasos guiados.
  • Cómo hacerlo: tareas concretas paso a paso.
  • Referencia: contratos, API, parámetros, límites.
  • Explicaciones: conceptos, porqués, arquitectura.

Si una guía mezcla enfoques, divídela o muévela a la categoría correcta.

  • Añade entradas explícitas en mkdocs.yml (secciones y orden lógico).
  • Si mueves/renombras páginas, añade redirects para evitar 404.

Última actualización

  • La fecha se muestra automáticamente con git-revision-date-localized. No la edites manualmente.

Cómo servir y compilar docs

python -m venv .venv && source .venv/bin/activate  # opcional
pip install -r docs/requirements.txt
mkdocs serve  # http://127.0.0.1:8000
# Build estricto
mkdocs build --strict

Checklist de PRs de documentación

  • [ ] Front-matter completo y H1 consistente
  • [ ] Ubicación correcta por Diátaxis y nav actualizado
  • [ ] Ejemplos con bloques de código y lenguajes correctos
  • [ ] Admonitions y/o tabs si hay alternativas
  • [ ] Links verificados; añade redirects si cambias rutas
  • [ ] Lint visual (render local con mkdocs serve)