Aller au contenu principal

Collaboration & Documentation – Wikis, sites statiques et knowledge base

Collaboration & Documentation – Wikis, sites statiques et knowledge base

Illustration de la collaboration et de la documentation

La documentation et la collaboration, c'est ce que tout le monde dit qu'il faut faire mais que personne ne fait vraiment. Face à la complexité croissante des systèmes, à la multiplication des équipes, et à la nécessité de partager la connaissance efficacement, les organisations doivent mettre en place des solutions adaptées pour documenter l'infrastructure, les processus, les runbooks, et les produits, tout en facilitant la collaboration et le partage de connaissances.

Rôle de cette rubrique​

Cette rubrique couvre les outils permettant de :

Documenter l'infrastructure, les processus, les runbooks, et les produits : créer et maintenir une documentation technique complète, accessible, et à jour. La documentation technique est essentielle pour comprendre les systèmes, les processus opérationnels, et les procédures de maintenance.

Partager la connaissance dans les équipes : faciliter le partage de connaissances entre les équipes, réduire la dépendance aux individus, et créer une mémoire organisationnelle. Les wikis et knowledge bases permettent de centraliser la connaissance et de la rendre accessible à tous.

Combiner docs statiques, wikis, knowledge base, et diagrammes : utiliser les bons outils pour chaque besoin. Les générateurs de sites statiques sont idéaux pour la documentation versionnée, les wikis pour la collaboration, et les outils de diagrammes pour la visualisation.

Grandes familles d'outils​

Générateurs de sites statiques pour docs-as-code

Les générateurs de sites statiques (Docusaurus, MkDocs, Hugo, Jekyll) transforment des fichiers Markdown en sites web statiques. Cette approche "docs-as-code" permet de versionner la documentation avec Git, de faciliter les contributions via merge requests, et d'intégrer la documentation dans les workflows de développement.

  • Docusaurus : orienté documentation produit et développeur, basé sur React, support MDX, c'est d'ailleurs avec ça que ce site tourne.
  • MkDocs : simple et Python-based, idéal pour documentation technique.
  • Hugo : très rapide, basé sur Go, adapté aux sites de documentation volumineux.
  • Jekyll : pionnier, basé sur Ruby, intégré avec GitHub Pages.

Wikis et knowledge base

Les wikis et knowledge bases (Wiki.js, Bookstack, HedgeDoc) offrent des interfaces web pour créer, modifier et partager de la documentation de manière collaborative. Ils sont idéaux pour la documentation interne, les runbooks, et la base de connaissances.

  • Wiki.js : wiki moderne avec interface intuitive, support Markdown.
  • Bookstack : knowledge base organisée en livres et chapitres.
  • HedgeDoc : éditeur collaboratif en temps réel pour notes et documentation.

Outils de diagrammes

Les outils de diagrammes (Draw.io / diagrams.net) permettent de créer des diagrammes, schémas, et visualisations pour compléter la documentation textuelle.

  • Draw.io : outil de diagrammes open source, intégré dans de nombreux outils.

Enjeux et bonnes pratiques​

Documentation versionnée avec Git

Documentation versionnée avec Git

La documentation versionnée avec Git permet de :

  • Tracker les changements et l'historique
  • Faciliter les contributions via merge requests
  • Intégrer la documentation dans les workflows CI/CD
  • Maintenir la cohérence avec le code source

Contributions facilitées

Les contributions facilitées via merge requests et revue permettent de :

  • Encourager les contributions de toute l'équipe
  • Maintenir la qualité via la revue de code
  • Créer une culture de documentation partagée

Différence entre doc "développeur" et doc "utilisateur / support"

  • Documentation développeur : API, architecture, processus de développement, runbooks techniques.
  • Documentation utilisateur / support : guides utilisateur, FAQ, procédures, base de connaissances.

Les outils doivent être adaptés au public cible et au type de documentation.

Importance d'avoir une source de vérité unique

Une source de vérité unique permet de :

  • Éviter la duplication et les incohérences
  • Faciliter la maintenance
  • Assurer que tout le monde consulte la même information
  • Réduire la confusion et les erreurs

Bénéfices​

  • Documentation accessible : documentation centralisée et facilement accessible.
  • Collaboration : faciliter le partage de connaissances et la collaboration.
  • Versionnement : tracker les changements et maintenir l'historique.
  • Intégration : intégrer la documentation dans les workflows de développement.
  • Maintenance : faciliter la mise à jour et la maintenance de la documentation.

Limites et défis​

  • Maintenance : maintenir la documentation à jour nécessite discipline.
  • Qualité : assurer la qualité et la cohérence de la documentation.
  • Adoption : encourager l'utilisation et les contributions.
  • Choix d'outil : choisir l'outil adapté au contexte et aux besoins.
  • Migration : migrer d'un outil à un autre peut être complexe.

La documentation et la collaboration nécessitent une approche structurée, des outils adaptés, et une culture de partage de connaissances.

Cette rubrique sert de repère pour choisir l'outil adapté au contexte : équipe, stack technique, niveau de maturité DevOps, besoin en intégration avec CI/CD, type de documentation, et public cible.