Portal interno de documentación técnica

Problema

La documentación de un ERP a medida se pudre cuando vive aparte del código. El documento se escribe una vez, el módulo cambia tres veces y nadie actualiza el documento porque está en otro sitio, con otro flujo de trabajo y otro permiso de edición.

Solución

Este portal invierte el flujo. La fuente de verdad sigue dentro de cada repositorio, junto al código que describe, en markdown plano; el portal la importa, la organiza y la publica como web de solo lectura para consultoría, soporte y administración.

Eso reparte bien las obligaciones. El programador nunca sale de su repositorio: documenta en el mismo commit en el que cambia el comportamiento, y la revisión de la documentación es la revisión del código. El resto del equipo nunca abre el repositorio: entra en una web, busca y lee.

La recolección se lanza sobre los repositorios y la publicación la hace MkDocs, que parte del mismo markdown que ya estaba escrito y genera un sitio estático sin nada que mantener detrás. El árbol de navegación se construye a partir de lo que se importa, no a mano, para que añadir documentación no obligue a editar un índice.

Arquitectura

Por qué está montado así

La fuente de verdad vive en el repositorio, junto al código. Así la documentación se revisa en el mismo commit que el cambio que la provoca.

La importación va en un solo sentido y el portal es de solo lectura. Con edición en los dos lados acabas con dos versiones y nadie sabe cuál manda.

Genero la navegación a partir de lo que se importa. Un índice mantenido a mano es lo primero que se queda atrás.

MkDocs y markdown plano, el mismo formato que el programador ya usa. El sitio es estático y no hay backend que administrar.

La recolección va en PowerShell, que se ejecuta donde ya están los repositorios.

Resultado

La documentación técnica del ERP se escribe una sola vez, dentro del repositorio, y el equipo que no programa la consulta en una web que se regenera desde esa misma fuente.