Pourquoi on a quitté Notion pour notre stack docs interne

Le contexte de départ

Septembre 2025. Devoria est encore une équipe de 12 développeurs. Notre doc interne est sur Notion : onboarding, runbooks, post-mortems, decisions architecture, revues de code, processes RH. Environ 480 pages, organisées dans 6 espaces.

Trois symptômes nous dérangent depuis quelques mois :

1. Le search rame quand la base passe les 300 pages.
2. Les permissions par sous-page deviennent un cauchemar à mesure qu'on grossit.
3. La doc technique (snippets de code, ADRs) vit à côté du code, pas avec.

On a regardé 4 alternatives. Ce qu'on a appris.

Critère de décision : où vit la doc ?

C'est la vraie question. Trois philosophies :

Doc dans un outil dédié (Notion, Confluence, Outline) : la doc est un produit à part. Elle a son propre cycle de vie, ses droits d'accès, son search.

Doc dans le repo Git (MDX, Markdown) : la doc vit avec le code. PR pour la modifier, review obligatoire, history Git, search depuis l'IDE.

Hybride : doc business dans un outil, doc technique dans le repo.

Notre choix après 6 mois de tests : hybride, avec une stack précise.

Ce qu'on a testé

Notion (l'incumbent)

Forces : prise en main rapide, bases de données puissantes, async par défaut. Faiblesses : search lent au-delà de 300 pages, permissions chaotiques, pas de versioning Git, pas de PR pour reviewer une modification.

Verdict : on l'a gardé pour la doc business / process RH / OKRs. Bon outil pour ça.

Confluence

Testé 2 semaines. Trop lourd, UI datée, recherche médiocre.

Verdict : abandonné rapidement.

Outline

Open-source, propre, search rapide. Faiblesses : pas d'écosystème templates, on aurait dû tout self-héberger.

Verdict : la meilleure alternative à Notion en mode "outil". On ne l'a pas adopté parce qu'on est partis sur du Markdown dans le repo.

Markdown / MDX dans le repo

C'est ce qu'on a fini par adopter pour la doc technique. Stack :

• Fichiers .md / .mdx dans le repo principal, dossier docs/.
• Astro ou Mintlify pour le rendu web (avec hot reload, search, syntax highlighting).
• Search via FlexSearch côté client, pas besoin de backend.
• Diagrammes en Mermaid (rendus côté client).
• ADRs (Architecture Decision Records) en .md numérotés.

Ce qu'on a gagné

1. La doc vit avec le code

Quand un dev modifie une fonction critique, il peut updater la doc dans la même PR. Le reviewer voit les deux. Si la PR n'est pas mergée, la doc n'est pas non plus. Cohérence garantie.

2. Un seul search

Notre IDE (Cursor) cherche maintenant dans le code ET la doc en même temps. Cmd+P retrouve un fichier doc aussi vite qu'un fichier code.

3. Versioning natif

Chaque modification de doc a un commit auteur, une date, et un message. On peut blame une ligne et savoir pourquoi elle a été ajoutée. Sur Notion, l'historique existe mais n'est pas branchable.

4. Templates partagés

Nos templates ADR, post-mortem, runbook, sont des fichiers du repo. Tout dev qui clone l'a, sans configurer un compte ou payer une licence.

Ce qu'on a perdu (et qui nous manque)

• L'édition fluide : Markdown reste moins agréable que Notion pour les non-devs.
• Les bases de données : on n'a plus de "table" interactive avec filtres. Pour les rares cas où on en a besoin, on a un Notion connecté.
• Le partage rapide en lecture : un lien Notion se partage en 1 clic. Pour la doc Markdown, on a un site interne en intranet.

C'est pour ces raisons qu'on garde Notion pour ~30 % de notre doc (business, RH, processes).

Ce qu'on conseille à nos clients PME tech

Si vous êtes < 5 devs : restez sur Notion. Le coût de migration n'est pas justifié.

Si vous êtes 5-15 devs avec une vraie doc technique : passez la doc tech (architecture, runbooks, ADRs) dans le repo. Gardez Notion pour le reste. C'est notre recommandation par défaut.

Si vous êtes > 15 devs ou une scaleup : tout dans Git. Mintlify ou un site Astro custom. Vous en aurez les moyens et le besoin.

Le coût de la migration

Pour les 240 pages techniques qu'on a migrées, ça nous a pris 3 jours :

• Jour 1 : export Notion (Markdown), nettoyage manuel des liens cassés.
• Jour 2 : restructure des dossiers, écriture des .astro pages d'index.
• Jour 3 : déploiement intranet + formation équipe.

Les 240 pages business sont restées sur Notion. Pas de migration big bang.

L'erreur qu'on a faillite faire

On a hésité à tout migrer d'un coup, business compris. On a renoncé après une journée de POC. Forcer un product manager à apprendre Markdown pour rédiger une fiche fonctionnelle, c'est une fausse bonne idée. Chaque outil son rôle.

Le pattern à retenir

Doc qui change avec le code → dans le repo. Doc qui change indépendamment du code → dans un outil dédié.

Cette ligne de séparation a éliminé 90 % de nos débats internes en 2 mois.

Si vous voulez de l'aide pour structurer votre doc technique (templates ADR, runbooks, intégration au site interne), parlez-nous. C'est typiquement une mission de 3-5 jours qu'on livre régulièrement à nos clients en croissance.