Seis servicios, seis conjuntos de notas,
y ninguna forma de leerlos juntos.
Las notas existen. Cada servicio tiene un README que merece la pena leer, la mayoría tiene una carpeta de arquitectura y alguien escribió un documento muy bueno sobre cómo funciona el flujo de pagos. Está en un repository que no has clonado.
Todas las herramientas que podrían presentar esto te piden elegir un repository y escribir un archivo de navegación para él. Ese modelo se pensó para un producto con un solo sitio de documentación, y no encaja con un equipo de plataforma con treinta repositories y ninguna gana de escribir treinta archivos de configuración.
Así que el conocimiento se queda donde se escribió, se encuentra con grep, si es que se encuentra, y se vuelve a deducir en una reunión cada pocos meses entre quienes estuvieron la última vez.
El multi-repository es la parte difícil de copiar a nivel de arquitectura: «un repository, un sitio» es una suposición que llega hasta el fondo de toda herramienta pensada para documentación pública.
Las partes que importan aquí
No toda la lista de funciones, sino las de las que depende este problema concreto.
Muchos repositories, un solo espacio de trabajo
Un proyecto contiene tantos repositories como le asignes. El árbol los muestra juntos, la búsqueda los abarca todos en una sola consulta y el acceso se concede una vez en el proyecto, no por repository.
La estructura de carpetas es la navegación
Treinta repositories son treinta archivos de navegación en cualquier otra herramienta. Aquí son treinta conexiones y ninguna configuración, porque la estructura que ya tienes es la que leemos.
Documentación por detrás del código
Una nota que nombra una ruta de código modificada después que ella se convierte en un hallazgo. En una plataforma, es la diferencia entre saber que tu documentación de arquitectura se desvió y descubrirlo durante una caída.
Diagramas a juego con la página
Mermaid se muestra con la paleta activa del producto en lugar de un tema genérico, y la vuelve a leer cuando cambias de tema. Un diagrama de secuencia en una nota de arquitectura es la razón de ser de la nota.
Agentes que citan en lugar de adivinar
Un agente de código que trabaja en un servicio puede leer lo que documentaron los otros cinco, con una URL que una persona puede abrir, en lugar de deducir tu arquitectura del código que tenga a mano en su contexto.
Un movimiento conserva su identidad
Reorganizar la documentación entre repositories es normal en un equipo de plataforma. Un archivo renombrado o movido sigue siendo el mismo documento, así que su estado de revisión, sus notas y sus hallazgos de salud se mueven con él en lugar de perderse en silencio.
Qué pasa de verdad
- 01Conecta los servicios de uno en unoCada uno lleva alrededor de un minuto y no necesita configuración. Agrúpalos en un proyecto con el nombre del dominio en lugar del repository.
- 02El árbol se monta soloRaíces de documentación encontradas por repository, títulos deducidos, orden aplicado, CHANGELOG y LICENSE plegados aparte. Nadie escribe una barra lateral.
- 03La búsqueda deja de ser por repositoryUna sola tecla para buscar en todos los servicios de la organización, con ranking, y la ruta y el estado de revisión junto a cada resultado.
- 04Concede el proyecto a un equipo, una vezEl acceso es el proyecto, no el repository, así que incorporar a alguien a la plataforma es una concesión en lugar de treinta.
- 05Apunta tus agentes a élUna clave limitada a ese proyecto, de solo lectura, con un umbral de revisión opcional para que un agente solo vea documentos que alguien ha validado.
- 06Observa cómo el código se aleja de las notasLos push que tocan rutas de código que nombran tus documentos se convierten en hallazgos. Es la única señal automática del producto que una persona no tuvo que registrar.
Qué no resuelve esto
Cada página de este sitio lleva una, por lo mismo: una página de caso de uso sin límites es un folleto.
- No lee tu código
- Nunca se obtiene nada fuera de la raíz de documentación. Vemos los nombres de las rutas de código modificadas en la carga del push, nunca su contenido, y eso es lo que abarata la señal de documentación por detrás del código y también lo que la limita.
- No genera diagramas
- El Mermaid que escribiste se muestra correctamente. No se deduce la arquitectura a partir de un grafo de dependencias, y no se va a hacer.
- Una organización, no una federación
- Los repositories se agrupan en proyectos dentro de una organización. Leer dos organizaciones distintas desde una misma vista no es algo que haga.