Outils et plateformes¶

L'outil ne remplacé pas la méthode — mais le mauvais outil tue la meilleure méthode.

Le mythe de l'outil qui va tout résoudre¶

"On va déployer Confluence et le problème de la documentation sera règle." Cette phrase a été prononcee dans des milliers de DSI, avec des résultats prévisibles. Trois mois plus tard, le wiki contient cent pages créées par enthusiasm lors du lancement, jamais relues depuis. Les équipes utilisent toujours Slack pour trouver l'information.

L'outil n'est pas neutre : un mauvais choix d'outil crée de la friction qui decourage les comportements de partage. Un outil trop complexe n'est pas utilisé. Un outil trop libre produit du chaos. Un outil sans intégration dans le flux de travail reste une activité séparée que tout le monde reporte. Mais un bon outil, aligné sur les pratiques de l'équipe et intégré dans son écosystème, amplifie une culture de capitalisation.

Le choix d'outil est donc une décision de management autant que technique : il faut comprendre les comportements que l'on veut encourager, les frictions existantes que l'on veut éliminer, et les contraintes d'intégration de l'écosystème en place.

Wikis : forces, faiblesses et pieges¶

MediaWiki¶

MediaWiki est le moteur qui fait tourner Wikipedia. Il est gratuit, extremement stable et supporte des volumes massifs de contenu. Sa syntaxe wikitexte est puissante mais deroute les utilisateurs non techniques.

Points forts :

• Gratuit et open source
• Recherche full-text mature
• Historique de versions robuste
• Extensions nombreuses (SemanticMediaWiki pour les metadonnees structurées)
• Haute disponibilité possible

Points de vigilance :

• Éditeur wikitexte peu ergonomique pour des utilisateurs habitues aux éditeurs WYSIWYG
• Interface datee sans theming adapté
• Administration et maintenance requierent des compétences techniques
• Peu intégré aux écosystèmes IT modernes (pas d'API REST native simple)

Contexte adapté : organisations avec de forts volumes de contenu stable, équipes techniques confortables avec le markdown/wikitexte, besoin de personnalisation avancee.

Confluence (Atlassian)¶

Confluence est la référence dans les écosystèmes Atlassian (Jira). Son avantage principal est l'intégration native avec Jira : les pages peuvent referencer des tickets, des sprints, des epics. Son modèle de prix à l'utilisateur peut devenir significatif à grande échelle.

Points forts :

• Intégration Jira (tickets, sprints, macros dynamiques)
• Éditeur WYSIWYG accessible
• Templates nombreux (retro, runbook, décision log, post-mortem)
• Confluence Cloud avec indexation Google Workspace / Microsoft 365
• API REST mature

Points de vigilance :

• Prix à l'utilisateur, coûteux pour les grandes organisations
• Tendance au wiki-sprawl : la facilite de création de pages encourage la proliferation
• Recherche parfois insuffisante sur de grands corpus
• Migrer depuis Confluence est difficile (lock-in fort)

Anti-patterns Confluence :

• Créer un espace par projet (proliferation d'espaces morts après clôture du projet)
• Exporter des documents Word dans des pages (le contenu n'est pas indexe correctement)
• Ne pas utiliser les templates (contenu hétérogène, navigation impossible)
• Confondre Confluence avec un drive (stocker des fichiers plutôt que du contenu)

Notion¶

Notion a popularise l'approche "blocks" et la flexibilite entre bases de données, wikis et documents. Il est particulièrement apprecie par les équipes produit et design pour son versatilite.

Points forts :

• Flexibilite du format (page, table, kanban, galerie, calendrier)
• Éditeur agreable, courbe d'apprentissage faible
• Bases de données relationnelles simples très utiles pour les catalogues
• Templates communautaires nombreux
• API API relativement ouverte

Points de vigilance :

• Recherche full-text limitee sur les grandes bases
• Performances degradees sur les workspaces très volumineux
• Hiérarchie de pages peut devenir complexe à naviguer
• Dépendance au vendor (SaaS uniquement)
• Droits d'accès granulaires parfois complexes a gérer

Contexte adapté : équipes de taille moyenne, mix produit/tech, besoin de flexibilite, peu de contenu très structure.

Knowledge bases modernes : structure vs liberté¶

Outline¶

Outline est une knowledge base open source orientée équipes de développement. Il adopte le markdown comme format natif, ce qui le rend naturel pour les équipes techniques.

Points forts :

• Open source (auto-heberge possible)
• Markdown natif avec éditeur hybride
• Collections et sous-collections pour la structure
• Droits granulaires par collection
• Intégration Slack, Figma, GitHub, Loom
• Recherche full-text efficace
• API REST documentee

Points de vigilance :

• Moins de templates pre-built que Confluence
• Fonctionnalités avancees (analytics, approbations) limitees en version communautaire
• Community plus petite que les outils majeurs

BookStack¶

BookStack organisé le contenu en livres, chapitres et pages — une metaphore qui structure naturellement le contenu hierarchique. Particulièrement adapté aux documentations techniques denses.

Points forts :

• Structure hierarchique claire (etagere > livre > chapitre > page)
• Open source, auto-heberge
• Export PDF natif
• Éditeur WYSIWYG + Markdown
• Recherche dans le texte des pages

Points de vigilance :

• La metaphore "livre" peut être rigide pour du contenu dynamique ou evenementiel
• Moins d'integrations natives que les concurrents
• Interface moins moderne que Notion ou Outline

Slite¶

Slite positionne comme alternative a Notion pour les équipes qui veulent la flexibilite sans la complexité. Accent mis sur la simplicité de l'éditeur et la collaboration en temps réel.

Points forts :

• Éditeur très accessible, collaboration en temps réel
• Organisation par canaux (inspire de Slack)
• AI assistant intégré (recherche semantique, synthèse)
• Templates adaptés aux workflows équipe

Points de vigilance :

• SaaS uniquement
• Moins mature sur les gros corpus
• Moins intégré dans les écosystèmes développeurs

Tableau comparatif¶

Moteurs de recherche internes¶

Le problème de la recherche dans la connaissance distribuée¶

L'information d'une DSI est rarement dans un seul endroit. Elle est distribuée entre le wiki, les tickets ITSM, la documentation technique dans les repos, les bases de runbooks, les archives d'incidents, les emails. La recherche silo par silo est inefficace : l'utilisateur ne sait pas dans quel silo chercher, et les résultats sont fragmentes.

Un moteur de recherche interne federe l'indexation de toutes ces sources et expose une interface de recherche unifiee. Il est l'infrastructure critique de la capitalisation : sans retrouvabilite, les connaissances capitalisees restent inaccessibles.

Elasticsearch¶

Elasticsearch est le moteur de recherche full-text de référence en enterprise. Il indexe des documents JSON et supporte des requêtes complexes avec scoring, facettes, suggestions et analyse linguistique.

Architecture typique DSI :

• Index par type de source (wiki, tickets, repos, runbooks)
• Connecteurs pour ingerer les sources (Logstash, connecteurs natifs, scripts custom)
• Kibana ou interface custom pour la recherche
• Relevance tuning par source et par type de contenu

Points forts :

• Très scalable (volumes illimités)
• Requêtes complexes (boosting par champ, filtres, aggregations)
• Analyse linguistique configurable (stemming, synonymes, stopwords)
• Écosystème mature (connecteurs, monitoring)

Points de vigilance :

• Complexité opérationnelle élevée (cluster a maintenir, tuning nécessaire)
• Pas de solution de recherche "out-of-the-box" : il faut construire l'interface et les connecteurs
• Expertise requise pour le tuning de la pertinence

Meilisearch¶

Meilisearch est un moteur de recherche open source conçu pour la facilite d'utilisation et la vitesse. Il fournit une recherche tolérante aux fautes de frappe avec une latence très faible (< 50ms typiquement).

Points forts :

• Installation et configuration simples (binaire unique)
• API REST intuitive
• Tolérance aux fautes de frappe native
• Facettes et filtres sans configuration complexe
• Interface de recherche rapide a construire
• Open source et auto-hebergeable

Points de vigilance :

• Moins adapté aux très grands volumes (dizaines de millions de documents)
• Moins de fonctionnalités avancees qu'Elasticsearch (aggregations complexes, ML ranking)
• Écosystème de connecteurs plus limite

Contexte adapté : équipes souhaitant une recherche interne fonctionnelle rapidement, corpus de taille modérée (< 1M documents), équipes sans expertise Elasticsearch.

Algolia¶

Algolia est le SaaS de référence pour la recherche as-a-service. Il externalise toute la complexité opérationnelle moyennant un abonnement.

Points forts :

• Zéro infrastructure a gérer
• Dashboard de configuration avancee (relevance, synonymes, ranking)
• SDK client nombreux
• Performances excellentes et garanties par SLA
• Analytics de recherche (que cherchent les utilisateurs, sans résultats, clicks)

Points de vigilance :

• Prix significatif à grande échelle
• Les données quittent l'infrastructure de l'organisation (contraintes de sécurité / RGPD)
• Moins adapté aux données très sensibles

Recherche semantique et AI¶

Les moteurs de recherche vectorielle (dense retrieval) permettent une recherche par sens et non uniquement par mots-clés. Un document sur "l'impact d'une saturation de pool de connexions" sera retrouve par une requête "pourquoi la base de données répond lentement" même sans les mots exacts.

Cette capacité est particulièrement utile pour les knowledge bases techniques ou la terminologie varie entre auteurs. Les solutions : pgvector (PostgreSQL), Weaviate, Qdrant, ou les fonctionnalités semantiques natives de Elasticsearch 8+.

Graphes de connaissances¶

Quand la hiérarchie ne suffit pas¶

Les structures hierarchiques (wikis, taxonomies) échouent quand la connaissance est relationnelle : un concept appartient a plusieurs catégories, un document est lie a plusieurs projets et plusieurs équipes, un composant hérité de caractéristiques de plusieurs predecesseurs.

Le graphe de connaissances représenté les entités et leurs relations sans imposer une hiérarchie unique. Chaque nœud est une entité (un concept, un document, un composant, une personne) ; chaque arete est une relation typee (dépend-de, référence, creé-par, remplacé, complemente).

Neo4j¶

Neo4j est la base de données de graphe de référence. Elle stocke des nœuds et des relations avec des propriétés, et expose Cypher comme langage de requête.

Cas d'usage DSI :

• CMDB augmentee : les CI et leurs dépendances dans un graphe interrogeable ("quels services sont impactes si ce serveur tombe ?")
• Graphe de connaissances des experts : qui connait quoi, qui a travaille sur quoi, qui peut répondre à quelle question
• Analyse d'impact des changements : traverser le graphe de dépendances pour identifier les consommateurs impactes
• Détection de composants orphelins ou en double

Exemple de requête Cypher :

// Quels services sont directement ou indirectement affectes
// si le service auth-service devient indisponible ?
MATCH path = (s:Service {name: 'auth-service'})<-[:DEPENDS_ON*1..3]-(consumer)
RETURN consumer.name, length(path) as distance
ORDER BY distance

Obsidian et Logseq¶

Obsidian et Logseq sont des outils de prise de notes orientes "graphe personnel" — chaque note peut referencer d'autres notes par des liens bidirectionnels, et le graphe des liens est visualisable.

Ils sont populaires pour les knowledge bases personnelles des architectes et des tech leads. La méthode Zettelkasten (Luhmann) s'y adapté bien : chaque note atomique est liee aux notes connexes, construisant progressivement un graphe de connaissances personnel.

Points forts :

• Fichiers Markdown locaux (pas de lock-in, versionnable avec Git)
• Graphe visuel des connexions
• Recherche rapide dans les notes locales
• Obsidian : écosystème de plugins riche
• Logseq : approche block-based, todo intégré

Points de vigilance :

• Non conçu pour le partage en équipe (pas d'edition collaborative native)
• Adoption individuelle, pas organisationnelle
• La qualité du graphe dépend de la discipline de l'auteur (liens manquants = graphe pauvre)

Contexte adapté : knowledge base personnelle des experts, préparation de talks et d'ADR, second brain pour les tech leads avec un volume élevé de connaissance a gérer.

Critères de choix d'une plateforme¶

Les questions a poser avant de choisir¶

Taille et structure de l'équipe. Une équipe de 10 personnes dans un seul site n'a pas les mêmes besoins qu'une DSI de 200 personnes distribuée sur plusieurs fuseaux. La complexité de gouvernance d'une grande plateforme n'est pas justifiee pour une petite équipe.

Nature du contenu dominant. Les procédures opérationnelles (runbooks) sont mieux servies par une structure rigide avec templates. Les ADR et les analyses sont mieux servies par un format libre. Les catalogues de services ou d'API necessitent des champs structures et une recherche par attribut.

Intégration avec l'écosystème existant. Un outil isole de l'écosystème de développement restera une activité séparée. L'intégration avec le ITSM (Jira, ServiceNow), les repos (GitHub, GitLab) et les outils de communication (Slack, Teams) est un facteur determinant d'adoption.

Qui produit le contenu. Si la documentation est produite principalement par des profils techniques, le Markdown et l'approche docs-as-code sont naturels. Si les contributeurs incluent des profils non techniques, un éditeur WYSIWYG accessible est nécessaire.

Coût total de possession. Le prix de la licence est rarement le coût dominant. L'administration, la maintenance, la formation, la migration de contenu et l'intégration représentent souvent plusieurs fois le coût de la licence.

Matrice de décision¶

Intégration avec l'écosystème de développement¶

Docs-as-code¶

L'approche docs-as-code traite la documentation avec les mêmes outils et le même workflow que le code :

• Documentation en Markdown versionneé dans le repo Git
• Revue de la documentation via des pull requests (même workflow que le code)
• Publication automatique via un pipeline CI/CD
• Historique, branches, diff : les mêmes mécanismes que pour le code

Avantages pour une DSI technique :

• La documentation évolue au même rythme que le code (proximity)
• La revue de la documentation est intégrée dans le workflow de code review
• La documentation est versionneé avec le code (cohérence historique)
• Les développeurs utilisent les mêmes outils (pas de friction contextuelle)

Generateurs de sites statiques pour la documentation :

Génération automatique de documentation¶

La documentation la plus à jour est celle qui est générée directement depuis la source de vérité.

Pour les API : OpenAPI / Swagger permet de générer la documentation de référence depuis les annotations du code. Swagger UI, Redoc ou Stoplight offrent des interfaces interactives générées depuis la spec. La spec OpenAPI peut être commitee dans le repo et la doc mise à jour automatiquement à chaque merge.

Pour le code : les outils de documentation inline (JSDoc, Javadoc, pydoc, rustdoc) génèrent la référence API depuis les commentaires du code. Ils ne remplacent pas la documentation de plus haut niveau (architecture, use cases) mais maintiennent la référence technique sans effort supplémentaire.

Pour l'infrastructure : Terraform et Pulumi permettent de générer de la documentation depuis les modules IaC (terraform-docs, par exemple). Les configurations Kubernetes peuvent être documentees avec des commentaires YAML exploites par des outils de génération.

Pour la CMDB : l'intégration avec les outils de provisioning (Terraform, Ansible, Helm) alimente la CMDB automatiquement lors des deployments — garantissant la cohérence sans saisie manuelle.

CI/CD de la documentation¶

Un pipeline CI/CD pour la documentation valide que la documentation est cohérente et publiee automatiquement.

flowchart LR
    PR["Pull Request\n(doc modifiee)"] --> Lint["Lint\nmarkdownlint\nspell check"]
    Lint --> Build["Build\nMkDocs / Docusaurus"]
    Build --> Preview["Preview\ndeploy (Netlify / Vercel)"]
    Preview --> Review["Review\ncommentaire PR"]
    Review --> Merge["Merge\nmain branch"]
    Merge --> Publish["Publication\nproduction"]

    style PR fill:#e3f2fd
    style Publish fill:#e8f5e9

Étapes typiques d'un pipeline doc :

1. Lint du Markdown (markdownlint, vale pour le style)
2. Vérification des liens (lien brise = erreur de build)
3. Build du site statique (erreurs de syntaxe detecetes)
4. Deploy preview sur une URL temporaire pour la revue
5. Publication automatique après merge sur main

Gouvernance de l'écosystème outillage¶

Le risque de l'empilement des outils¶

Les DSI accumulent souvent des outils de documentation sans en retirer les anciens : Confluence pour les projets historiques, Notion adopte par les nouvelles équipes, un GitBook pour la doc publique, des wikis GitHub par repo. Le résultat est une information distribuée sans point d'entree unifie, et une charge cognitive pour les utilisateurs qui ne savent pas ou chercher.

La consolidation périodique de l'écosystème outillage est une responsabilité de gouvernance : identifier les outils en double, déprécier ceux qui ne sont plus actifs, et maintenir une carte simple de "quel outil pour quel usage".

Mesurer l'adoption¶

Un outil non utilisé est un outil inutile. Les métriques d'adoption a suivre :

Ces métriques doivent être visibles — intégrées dans un dashboard de sante de la base de connaissances — et revues périodiquement en équipe. La sante de la documentation n'est pas un sujet d'audit annuel ; c'est un indicateur opérationnel qui se surveille en continu.

La revue trimestrielle de la base de connaissances¶

Une revue trimestrielle de la base de connaissances est une pratique de gouvernance simple et efficace. Elle consiste à :

1. Identifier les articles non consultes depuis plus de 6 mois (candidats à l'archivage)
2. Identifier les articles signales comme douteux (a mettre à jour ou a supprimer)
3. Identifier les sujets fréquemment rechercheés sans résultat pertinent (gaps a combler)
4. Valider que les propriétaires de section sont toujours actifs
5. Mettre à jour la carte de l'écosystème outillage si des changements ont eu lieu

Cette revue peut être animee par le Knowledge Manager ou le responsable de la documentation — qui peut être une responsabilité tournante dans les équipes sans poste dédié.