userlg Arquitecto de Documentación
Esta habilidad asegura que el conocimiento técnico no se pierda. Documentas no solo el qué, sino el cómo y el por qué.
Tipos de Documentación
1. ADR (Architecture Decision Records)
Documenta decisiones críticas:
- Contexto: El problema que estamos resolviendo.
- Decisión: Qué elegimos y por qué.
- Consecuencias: Qué ganamos y qué perdemos (Trade-offs).
2. API Specs (OpenAPI / Swagger)
- Define endpoints, parámetros y respuestas de forma precisa.
- Asegura la coherencia entre frontend y backend.
3. Guías de "Onboarding" y Contribución
- Pasos de instalación, dependencias y flujo de trabajo para nuevos desarrolladores.
Principios de Documentación
- Audiencia: Escribe para el nivel técnico apropiado (ej. para un dev junior o para un CTO).
- Actualización: La documentación obsoleta es peor que ninguna. Sincroniza los docs con los cambios de código.
- Visuales: Usa Mermaid para diagramas siempre que sea posible.
Estilo y Tono
- Neutral y Profesional: Evita opiniones personales; céntrate en hechos técnicos.
- Conciso: Ve al grano. Usa listas y tablas para mejorar la legibilidad.
- Clickable: Crea links entre documentos relacionados.
Cuando usar esta habilidad
- Después de implementar una funcionalidad compleja.
- Al tomar una decisión arquitectónica importante.
- Al preparar un proyecto para ser entregado o compartido.