Mantener y traducir

La documentación forma parte del proyecto: cada cambio debe ser trazable a una implementación, a una decisión confirmada o a una propuesta identificada como tal. Mantener español e inglés en la misma merge request evita que un idioma describa un comportamiento distinto.

Organización de las fuentes

Ubicación	Uso
docs/es/	Contenido español
docs/en/	Contenido inglés con las mismas rutas
docs/assets/	Diagramas e imágenes compartidos del contenido
theme/assets/	CSS, logotipo y runtime local de Mermaid
theme/overrides/	Adaptaciones pequeñas del tema
mkdocs.es.yml, mkdocs.en.yml	Menús de navegación traducidos
third_party/	Licencias y procedencia de recursos redistribuidos

El build incorpora los recursos compartidos en ambos sitios. Edita su fuente una sola vez. Los directorios public/ y .build/ son salidas; una modificación hecha directamente en ellos desaparece en la siguiente compilación.

Cambiar o añadir una página

1. Crea una rama de documentación, por ejemplo docs/update-infrastructure.
2. Edita el archivo español y su equivalente inglés. Conserva el mismo nombre y ruta relativa, como infrastructure/state.md.
3. Si añades una página, inclúyela en mkdocs.es.yml y mkdocs.en.yml con un título adecuado para cada idioma.
4. Revisa enlaces y referencias afectadas por el cambio.
5. Ejecuta la construcción completa y revisa visualmente las páginas modificadas.
6. Abre una merge request explicando qué comportamiento se documenta, su fuente y cualquier decisión todavía pendiente.

No se añade automáticamente una traducción de relleno si falta un archivo: la comprobación de paridad falla. Esto permite detectar omisiones antes de publicar.

Usar evidencia verificable

Al actualizar un detalle de Terraform, CI/CD o Kubernetes, conserva el nombre del repositorio, la ruta del archivo y el commit revisado. Siempre que sea posible, usa un enlace permanente /-/blob/<commit>/<ruta> en lugar de un enlace a una rama mutable.

Para una afirmación de la memoria, cita el capítulo o apartado y la página; diferencia la página física del PDF de la numeración impresa cuando no coincidan. El mapa de la memoria y la página de fuentes organizan esas correspondencias.

Distingue estos casos en la redacción:

Tipo	Cómo presentarlo
Implementación observada	Describe el comportamiento y cita el archivo y commit.
Afirmación de la memoria	Atribuye la afirmación al documento y conserva la referencia.
Interpretación	Explica el razonamiento y qué parte no se ha comprobado directamente.
Mejora propuesta	Identifícala como propuesta, sin presentarla como una función existente.
Motivo de diseño desconocido	Regístralo como pregunta al autor o decisión pendiente.

Un archivo de pipeline muestra qué se ha configurado, pero no demuestra por sí solo que un job haya terminado correctamente. Un recurso Terraform declara una intención, pero no prueba que siga existiendo en una cuenta cloud. Las evidencias de ejecución necesitan una fecha y una fuente específica.

Estilo y traducción

• Escribe para alguien que necesita comprender, reproducir u operar el proyecto.
• Mantén nombres de jobs, variables, rutas, recursos y comandos exactamente como aparecen en las fuentes.
• Traduce la explicación y los títulos; no traduzcas identificadores técnicos.
• Explica primero el propósito y después los comandos o detalles.
• Usa una tabla cuando exista una correspondencia concreta de variables, entornos, jobs o recursos.
• Señala los valores de ejemplo y los parámetros que debe sustituir quien reproduce el despliegue.
• Mantén las dos versiones equivalentes en alcance, incluidas las limitaciones y las preguntas pendientes.

Las traducciones pueden tener anclas diferentes porque los títulos cambian. Enlaza dentro de cada idioma a sus propios títulos. El selector de idioma conserva la página; no se utiliza como traducción automática de un fragmento concreto.

Enlaces y diagramas

Los enlaces entre páginas usan rutas relativas a archivos Markdown:

[Estado de Terraform](../infrastructure/state.md)
[Publicación](publishing.md)

MkDocs transforma esas rutas en URLs del sitio y valida sus destinos. Evita enlazar directamente a public/ o escribir URLs que empiecen por /es/: una raíz absoluta puede ignorar la subruta del proyecto en Pages.

Los diagramas Mermaid se escriben dentro de bloques de código. Mantén cada diagrama centrado en una relación concreta y utiliza una dirección vertical cuando crezca demasiado en horizontal:

```mermaid
flowchart TD
  C[Commit] --> V{Validation}
  V -->|Pass| P[Publish]
  V -->|Fail| R[Review]
```

El runtime se distribuye dentro del repositorio; no hace falta consultar un CDN al ver un diagrama. Los gráficos deben representar la implementación revisada y diferenciar una arquitectura propuesta de la actual. Añade texto equivalente alrededor del diagrama para que la explicación también sea comprensible sin la imagen.

Los recursos compartidos propios pueden situarse en docs/assets/. Desde una página en docs/es/infrastructure/, por ejemplo, un recurso docs/assets/diagrams/network.svg se enlaza como ../assets/diagrams/network.svg después de que el build lo incorpore a la raíz del idioma. En Markdown, la ruta se interpreta desde la ubicación de la página.

Validar antes de integrar

Con el entorno virtual ya instalado:

.venv/bin/python scripts/check_docs.py
.venv/bin/python scripts/build_docs.py

El primer comando es una comprobación rápida de las fuentes. El segundo ya incorpora esa comprobación y valida además la compilación y el HTML resultante. Para una revisión ordinaria basta ejecutar el segundo.

El modo estricto convierte los avisos de enlaces o navegación en errores del build. La validación adicional comprueba también los enlaces de cambio de idioma y los recursos estáticos. Los enlaces externos se revisan por separado cuando el cambio afecte a su contenido o destino.

Para revisar la presentación:

.venv/bin/python scripts/build_docs.py --serve

Comprueba el título, los bloques de código, el ancho de las tablas y los diagramas, el menú de idioma y una pantalla estrecha. El generador comprueba rutas y estructura; la revisión visual comprueba que la explicación sea legible.

Actualizar herramientas

requirements.in enumera las dependencias directas. requirements.txt fija el conjunto completo probado en Python 3.12; el pipeline instala este último. Actualiza ambos conscientemente en una rama y prueba el sitio completo en los dos idiomas antes de integrar. La imagen CI sigue la línea python:3.12-slim, por lo que puede recibir actualizaciones de la imagen base.

El tema elegido es Material for MkDocs 9.8.0. Su proyecto anuncia mantenimiento hasta el 5 de mayo de 2027; planifica una revisión del tema antes de esa fecha conservando las fuentes Markdown y MkDocs como generador solicitado. Esta fecha pertenece al tema, no es una declaración del estado de soporte de todas las dependencias. Aviso del mantenedor en PyPI.

El runtime Mermaid incorporado tiene su versión, URL de origen e integridad en third_party/mermaid/version.json. Si se sustituye, conserva su licencia y verifica una página con diagramas. Las plantillas adaptadas de Material también conservan su licencia en third_party/.

Qué debe explicar una merge request

Describe el cambio de comportamiento o la corrección documental, las fuentes revisadas y el resultado de la compilación. Si una decisión no está confirmada, referencia la pregunta correspondiente en Decisiones. Una merge request de documentación no debe convertir una hipótesis en una conclusión ni declarar resultados de despliegue que no se hayan observado.