Internal technical documentation portal fed from the repositories

Problem

Documentation for a custom ERP rots when it lives away from the code. The document gets written once, the module changes three times and nobody updates the document because it sits somewhere else, with a different workflow and different edit permissions.

Solution

This portal inverts the flow. The source of truth stays inside each repository, next to the code it describes, in plain markdown; the portal imports it, organises it and publishes it as a read-only site for consultancy, support and administration.

That splits the obligations sensibly. Developers never leave their repository: they document in the same commit that changes the behaviour, so reviewing the documentation is reviewing the code. Everyone else never opens the repository: they open a website, search and read.

Collection runs against the repositories and publishing is handled by MkDocs, which starts from the markdown already written and produces a static site with nothing to maintain behind it. The navigation tree is built from what gets imported rather than by hand, so adding documentation does not mean editing an index.

Architecture

Why it is built this way

The source of truth lives in the repository, next to the code. Documentation is reviewed in the same commit as the change that caused it.

The import runs one way and the portal is read-only. Allow edits on both sides and you end up with two versions and nobody knowing which one rules.

I generate the navigation from what gets imported. A hand-maintained index is the first thing to fall behind.

MkDocs and plain markdown, the same format developers already use. The site is static and there is no backend to administer.

Collection runs in PowerShell, which executes where the repositories already are.

Result

The ERP's technical documentation is written once, inside the repository, and the non-developing part of the team reads it on a site regenerated from that same source.