Documenter¶
La documentation technique est le vecteur de transmission du savoir dans une organisation. Sans plateforme centralisee, les connaissances se dispersent dans des wikis informels, des fichiers partages et des emails — impossibles a gouverner, a auditer ou a securiser. Le service documentaire fournit une plateforme unique pour héberger, générer et diffuser la documentation avec un contrôle d'accès aligne sur le modèle de classification des données.
Pourquoi un service documentaire dedie ?¶
Documentation-as-Code¶
Traiter la documentation comme du code apporte les mêmes benefices que le développement logiciel :
| Pratique | Benefice |
|---|---|
| Versionne (Git) | Historique complet, diff, blame, rollback |
| Revue par PR | Relecture avant publication, qualité du contenu |
| Build automatise | Génération du site à chaque push, zero intervention manuelle |
| Format texte (Md) | Editable avec n'importe quel éditeur, portable, perenne |
| Déploiement CI/CD | Publication automatique, reproductible, auditable |
Gouvernance et sécurité¶
Toute la documentation n'a pas le même niveau de sensibilite. Une procedure operationnelle interne, un schema d'architecture confidentiel et un tutoriel public n'ont pas les mêmes exigences d'accès. Le service documentaire integre nativement le modèle de classification pour controler au build quelles pages sont servies a quels lecteurs.
Classification¶
| Propriété | Valeur |
|---|---|
| Zone de confiance | Services d'entreprise |
| Niveau | Interne (le service lui-même) |
| Justification | La plateforme sert tous les collaborateurs authentifies |
| Contenu heberge | De Public a Restreint selon la classification de chaque page |
| Référence | Classification et zones de confiance |
Le contenu heberge peut etre de n'importe quel niveau
Contrairement a un service dont les données sont homogènes, la plateforme documentaire heberge des contenus de tous niveaux de classification. Le système de multi-build garantit que chaque lecteur ne reçoit que le contenu correspondant a son habilitation.
Solutions evaluees¶
| Solution | Licence | Modèle | Recommandation |
|---|---|---|---|
| MkDocs Material | MIT | Self-hosted | Recommandee |
| Docusaurus | MIT | Self-hosted | Alternative |
| Confluence | Commercial | SaaS/Server | Alternative |
| BookStack | MIT | Self-hosted | Alternative |
La solution recommandee est MkDocs Material : generateur de site statique, source Markdown versionnee dans Git, theme Material riche, extensible par plugins Python, complexité operationnelle minimale.
Chapitres¶
| Chapitre | Sujet |
|---|---|
| Fondamentaux | Documentation-as-Code, SSG, MkDocs, modèle Diataxis, vocabulaire |
| Comparaison des solutions | Grille multi-critères MkDocs vs Docusaurus vs Confluence vs BookStack |
| Architecture de référence | Multi-build par classification, plugin de filtrage, reverse proxy OIDC |
| Installation et configuration | MkDocs Material, plugin classification-filter, pipeline CI, Caddy, Keycloak |
| Integration | SCM, CI/CD, IAM, DNS, observabilité |
| Confidentialite | Isolation des builds, modèle de menaces, journalisation, revocation |
| Bonnes pratiques et cas avances | HA, migration, multi-langue, gestion des assets, troubleshooting |
Dependances¶
graph LR
IAM["IAM (Keycloak)"] --> Proxy["Reverse Proxy (Caddy)"]
Proxy --> Docs["Documentation (MkDocs builds)"]
SCM["SCM (Gitea)"] --> CICD["CI/CD (Gitea Actions)"]
CICD --> Docs
DNS["DNS interne"] --> Proxy
Docs --> Obs["Observabilite (Prometheus / Loki)"]