Toevoegen richtlijn voor documentatie #28
Description
Documentatie rondom projecten kon ik nog niet terugvinden in NeRDS, maar is natuurlijk wel een relevant aandachtspunt rondom digitale systemen. Dit punt richt zich vooral op projecten waarbij we zelf software ontwikkelen, maar hoeft zich niet daartoe te beperken. Diverse oplossingen hebben hun voor en nadelen, maar het lijkt mij handig om een voorkeur (of short list met een of twee voorkeuren) te hebben zodat we ook hier een golden path neer kunnen zetten.
In de projecten vanuit AI Validatie team en het Algoritmekader hebben we gewerkt met Material for MkDocs. Ook projecten zoals FastAPI en Ruff maken hier gebruik van. Markdown i.c.m. met MkDocs is fijn, je kan diagrammen maken en de search via Material for MkDocs met pre-views is goed.
Binnen het MijnOverheid Zakelijk project zie ik dat we gebruik maken van Structurizr. Dit werkt ook met documentatie in Markdown, maar het is wat meer gebouwd rondom software documentatie om o.a. Diagrammen te beschrijven. Er zit een search in, maar die werkt wat minder soepel. Wel kunnen er out-of-the-box bijv. beslissingen (ADRs) worden vastgelegd.
In andere projecten, bijv. developer.overheid.nl, zie ik ook Docusaurus terugkomen. Wederom documentatie in Markdown, maar opzet net weer anders. O.a. search zie je dat ze vaak een externe tool gebruiken via algolia. Dit laatste lijkt mij niet handig, omdat je dan voor search afhankelijk bent van een API (dus niet statisch) en je eens per zoveel tijd een crawl actie moet doen. Search is daarmee niet altijd up-to-date.
Bij Logius werken ze met ReSpec documentatie. Gaat wel via Markdown, maar het werkt net anders. By default zit hier geen search in. Voorbeelden zijn Logboek Dataverwerkingen en Handleiding herziene Wet hergebruik overheidsinformatie.
Bij OpenKat van VWS zie ik dat ze Sphinx gebruiken. Wederom Markdown gebaseerd, maar ook net weer anders.
Ook Quarto heb ik voorbij horen komen, maar een voorbeeld van open gebruik heb ik niet kunnen vinden.
Het werkt allemaal net anders, en ook styling is daardoor overal iets wat net anders werkt. Het lijkt mij goed om hier in NeRDS een voorkeurs oplossing neer te zetten waar ook een goed default template voor staat, zodat de basis configuratie met o.a. styling, search, etc. goed staat. Een (kort) vergelijkend onderzoek zal wel nodig zijn om te kijken wat de pros en cons zijn van de verschillende oplossingen.