Cómo escribir, revisar y mantener capítulos¶
Esta guía se redacta para consultarse durante toda la vida de un proyecto. No basta con explicar qué es un patrón: el lector debe saber si le sirve ahora y qué coste tendrá usarlo.
El estilo de escritura¶
Abrí con el problema real, no con una definición de diccionario. Describí una solución mínima antes de presentar una arquitectura sofisticada. Separá lo que está demostrado en motores o bibliografía de las recomendaciones que sintetizamos aquí.
Un tono técnico y narrativo resulta más claro que una lista interminable de patrones. Usá ejemplos que se puedan seguir de principio a fin: qué intentó hacer un personaje, qué validó la simulación, qué estado cambió y cómo se refleja.
Estructura recomendada para una guía¶
- Contexto: cuándo aparece el problema.
- Modelo mental y responsabilidades.
- Solución mínima, con pseudocódigo o diagrama.
- Alternativas y costes.
- Señales para evolucionar y antipatrones.
- Pruebas de aceptación y métricas.
- Enlaces a conceptos relacionados y fuentes externas.
Una ficha de patrón sigue una estructura parecida, pero estudia una técnica puntual. Una receta debe combinar varias técnicas para resolver una funcionalidad completa.
Enlaces tipo Obsidian¶
Cada artículo tiene un ID estable en su front matter:
---
id: foundation-authority
---
Podés referenciarlo desde cualquier otro archivo con dos formas:
[[foundation-authority]]
[[foundation-authority|límites de autoridad]]
El script scripts/prepare_docs.py convierte esos enlaces a rutas Markdown reales antes de generar el sitio y agrega la sección Mencionado desde a cada artículo enlazado. Esto permite mover un capítulo de carpeta sin editar todos sus enlaces.
El preparador falla si detecta un ID duplicado o un destino desconocido. No se deben usar IDs de artículos que todavía no existen: registralos en Hoja de ruta de la documentación hasta redactarlos. Los enlaces wiki en bloques fenced se dejan sin modificar para que podamos enseñar su sintaxis.
Documentar decisiones del juego¶
Un registro de decisión arquitectónica (ADR) debería incluir estado, contexto, alternativas, decisión, razones, consecuencias y condiciones de revisión. No transformes cada función en un ADR: reservá el formato para decisiones cuyo cambio afectaría varios módulos.
Etiquetar el estado de un capítulo¶
Distinguí entre contenido estable y revisado, guía inicial y tema reservado para desarrollar. Nunca confundas una entrada en el roadmap con un capítulo completo.
Referencias¶
Priorizá documentación oficial, textos originales y proyectos reales. No copies capítulos de libros o artículos enteros. Conservá URLs por tema y fechas/versiones cuando influyan en la recomendación.
Relacionado: ¿Por dónde empiezo?, Principios de una arquitectura evolutiva, Fuentes y bibliografía técnica, Hoja de ruta de la documentación.