Estándares de documentación técnica
La documentación técnica asegura la trazabilidad, la mantenibilidad y el entendimiento de los sistemas de Crehana. Este estándar establece una base común para documentar cambios técnicos de forma clara, proporcional y útil para ingeniería.
Por qué existe
A medida que los productos y servicios evolucionan, los cambios —grandes o pequeños— impactan múltiples componentes, equipos y flujos. Sin documentación clara y consistente, el conocimiento queda disperso en código, tickets o conversaciones, y eso dificulta el mantenimiento y la toma de decisiones futuras.
Propósito
- Proveer un lenguaje y una estructura compartida para documentar cambios técnicos.
- Facilitar la trazabilidad histórica de decisiones y modificaciones en el sistema.
- Reducir la dependencia del conocimiento implícito o tribal.
- Asegurar que cualquier integrante de ingeniería pueda entender los cambios con el paso del tiempo.
- Mantener el balance entre buena documentación y agilidad.
Estos estándares no reemplazan documentos de producto como el PRD: los complementan desde una perspectiva puramente técnica.
Alcance
Los estándares aplican a:
- Cambios en backend, frontend y data.
- Servicios, subgraphs, APIs, workers y procesos batch.
- Cambios de comportamiento, reglas de negocio, performance o arquitectura.
No cubren:
- Definición de problemas de negocio.
- Objetivos, KPIs, user stories o flujos funcionales de producto: eso vive en el PRD.
Principios
- La documentación es una ayuda, no una carga. Aporta claridad y valor; evita la burocracia innecesaria.
- El nivel de detalle es proporcional al impacto. No todos los cambios requieren la misma profundidad.
- La trazabilidad importa más que la extensión. Es preferible un documento corto y claro a uno extenso y difícil de mantener.
- La documentación evoluciona con el sistema. No es un artefacto estático: se actualiza cuando el comportamiento cambia.
Documentos complementarios
El estándar se apoya en dos documentos que todavía viven en Confluence:
- Plantilla de documentación técnica — define la estructura base para documentar un cambio técnico: redacción consistente, información relevante que no se omite y lectura fácil entre equipos. Adapta la plantilla al tipo y tamaño del cambio: completa solo las secciones que aplican.
- Estándar de documentación técnica por nivel de cambio — define qué se recomienda documentar según el impacto del cambio: pequeño, medio o grande. Úsalo para determinar el nivel de detalle esperado, evitar sobre-documentar cambios pequeños y asegurar contexto suficiente en los de mayor impacto.