ADR-0011 — VitePress pour la documentation technique
Status : Accepted Date : 2026-04 (rétroactif) Deciders : équipe plateforme Nex Tickets : —
Contexte
La documentation technique de Nex doit servir 4 audiences (dev, sec, QA, audit-bank), être versionnée avec le code, supporter Markdown + diagrammes Mermaid, et être déployée facilement.
Options envisagées :
- Confluence (Atlassian) — déjà utilisé pour la gouvernance produit.
- Notion — usage casual interne.
- Docusaurus, MkDocs Material, VitePress, Nextra.
Décision
- VitePress 1.x comme générateur de site statique pour la doc technique.
- Source :
apps/docs/versionné dans le monorepo (même cycle de revue que le code). - Stack : Markdown + Mermaid + recherche locale native.
- Déploiement : Cloudflare Pages sur
docs.paywithnex.com(cf. ADR-0010 et /operations/cicd-deploy-docs). - Confluence reste pour les artefacts produit non-techniques (specs PM, briefs CEO, etc.).
Conséquences
Positives
- Doc et code dans la même MR (revue alignée, drift moins probable).
- Markdown standard, portable.
- Build rapide (<5 s pour 100 pages).
- Mermaid natif (sequence, state, ERD, C4 lite).
- Search local sans dépendance externe.
- Coût d’hébergement nul (Cloudflare Pages plan free).
Négatives / risques
- Pas de WYSIWYG — frein pour les contributeurs non-tech (mitigé : la section
usage/est suffisamment simple en Markdown). - Pas de commentaires inline comme dans Confluence (mitigé : feedback via PR review).
- Pas de versionning fonctionnel (vue par version produit) — option Algolia DocSearch si besoin futur.
Alternatives écartées
- Confluence pour la doc technique — drift garanti vs code, pas Markdown, pas Mermaid natif, payant.
- Docusaurus — équivalent VitePress mais React vs Vue, moins natif sur monorepo Vite.
- MkDocs Material — Python, hors stack Nex.
- Nextra — bon mais lié à Next.js qu’on n’utilise pas.
Suivi
- Voir /governance/doc-conventions pour la convention frontmatter.
- Voir /operations/cicd-deploy-docs pour le pipeline.
- VitePress 2 à monitorer pour upgrade futur.