Documentación y ADRs
Archyl proporciona potentes funciones de documentación que te permiten crear documentación rica y enlazada junto a tus diagramas de arquitectura. Mantén tu conocimiento arquitectónico organizado y conectado.
Creando Documentación
Documentación Manual
Para crear documentación manualmente:
- Ve a la pestaña Docs en tu proyecto
- Haz clic en Nuevo Doc
- Ingresa un título y escribe tu contenido en Markdown
- Agrega etiquetas para organización
- Haz clic en Guardar
La documentación soporta sintaxis Markdown completa incluyendo:
- Encabezados y formato
- Bloques de código con resaltado de sintaxis
- Tablas y listas
- Imágenes y enlaces
Importando desde Git
Puedes importar documentación existente desde tu repositorio Git:
- Ve a Configuración del Proyecto > Descubrimiento de Documentación
- Configura tu conexión al repositorio
- Haz clic en Descubrir Docs
- Revisa y aprueba la documentación descubierta
Esto es perfecto para importar archivos README existentes, especificaciones técnicas o contenido wiki.
Enlazando a Elementos de Arquitectura
La documentación se vuelve más poderosa cuando está enlazada a tu arquitectura:
Creando Enlaces
- Abre una página de documentación
- Haz clic en Enlazar a Elemento
- Busca o navega al elemento de arquitectura
- Selecciona el/los elemento(s) a enlazar
- Haz clic en Listo
Viendo Documentación Enlazada
Al ver un elemento en el diagrama, la documentación enlazada aparece en el panel de detalles. Esto proporciona contexto instantáneo sin salir de la vista del diagrama.
Casos de Uso para Enlazar
- Enlazar documentación API a contenedores de Servicio
- Enlazar guías de configuración a componentes de infraestructura
- Enlazar especificaciones de diseño a contextos de sistema
- Enlazar comentarios de código a elementos de Código
Architecture Decision Records (ADRs)
Los ADRs documentan decisiones arquitectónicas importantes con su contexto y consecuencias.
¿Qué es un ADR?
Un Architecture Decision Record captura:
| Campo | Descripción |
|---|---|
| Título | Qué se decidió |
| Estado | Propuesto, Aceptado, Deprecado, o Reemplazado |
| Contexto | Por qué esta decisión era necesaria |
| Decisión | Qué se decidió |
| Consecuencias | Impacto de la decisión |
Creando un ADR
- Ve a la pestaña Decisiones en tu proyecto
- Haz clic en Nuevo ADR
- Completa los campos del ADR
- Enlaza a elementos de arquitectura relevantes
- Haz clic en Guardar
Flujo de Trabajo ADR
Los ADRs siguen un ciclo de vida:
- Propuesto: Borrador inicial, en discusión
- Aceptado: La decisión ha sido tomada y aprobada
- Deprecado: Ya no es relevante pero se mantiene para historial
- Reemplazado: Sustituido por una decisión más nueva
Descubrimiento de ADR
Como la documentación, los ADRs pueden ser descubiertos desde tu repositorio:
- Ve a Configuración del Proyecto > Descubrimiento de ADR
- Configura la ruta a tus ADRs (ej:
docs/adr/) - Haz clic en Descubrir ADRs
- Revisa y aprueba los registros descubiertos
Mejores Prácticas
Mantén la Documentación Actualizada
- Actualiza docs cuando la arquitectura cambie
- Revisa la documentación durante retrospectivas de sprint
- Usa ADRs para decisiones significativas
Enlaza Todo
- Cada sistema debería tener un doc de descripción
- Enlaza ADRs a componentes afectados
- Haz referencias cruzadas de documentación relacionada
Usa Etiquetas Efectivamente
- Etiqueta por dominio (auth, pagos, etc.)
- Etiqueta por tipo (api, guía, spec)
- Etiqueta por estado (borrador, revisión, final)
Guías de ADR
- Crea ADRs para decisiones significativas
- Incluye alternativas consideradas
- Documenta las compensaciones
- Enlaza a PRs de implementación cuando sea posible
Configuración de Descubrimiento de Documentación
Configura cómo se descubre la documentación:
Patrones de Ruta
Especifica qué rutas escanear:
docs/
wiki/
README.md
*.md
Patrones de Exclusión
Omite ciertos archivos:
node_modules/
vendor/
CHANGELOG.md
Próximos Pasos
- Descubrimiento con IA - Descubrir arquitectura automáticamente
- Compartir e Integrar - Compartir documentación externamente
- Exportar - Exportar documentación con diagramas