Notation est une solution innovante qui simplifie la gestion de la documentation technique en permettant aux développeurs de publier directement leurs documents Markdown sur Notion. Cet outil s'adresse particulièrement aux équipes de développement qui souhaitent intégrer leur documentation au sein de leur flux de travail, sans avoir à recourir à des services externes ou à des frameworks complexes.
L'approche de Notation repose sur plusieurs principes clés :
-
Intégration avec le code : La documentation doit vivre avec le code, ce qui signifie qu'elle doit être gérée dans le même dépôt que le code source. Cela facilite les mises à jour et assure que la documentation est toujours synchronisée avec le code.
-
Simplicité d'utilisation : Notation élimine la nécessité de se connecter à des services externes pour mettre à jour la documentation. Tout se fait directement à partir du dépôt de code, ce qui réduit la complexité et les risques d'erreurs.
-
Focus sur Markdown : Notation utilise Markdown comme seul framework de frontend, offrant ainsi une simplicité et une flexibilité maximales. Les utilisateurs n'ont pas besoin de se familiariser avec des technologies complexes comme React ou de déployer des sites web.
-
Accessibilité : La documentation générée par Notation est accessible à tous, y compris aux non-ingénieurs. Cela inclut les utilisateurs finaux et les membres de l'équipe produit, qui peuvent facilement consulter et comprendre la documentation.
-
Recherche optimisée : Notation tire parti des fonctionnalités de recherche et d'IA de Notion pour rendre la documentation hautement consultable. Cela permet aux utilisateurs de trouver rapidement les informations dont ils ont besoin.
-
Processus de revue et CI : La documentation est soumise au même processus de revue et d'intégration continue que le code, assurant ainsi sa qualité et sa pertinence.
Pour utiliser Notation, les développeurs doivent simplement écrire leur documentation en Markdown, créer une page Notion pour héberger cette documentation, et configurer une clé API Notion dans un fichier Notation.toml. Une fois configuré, ils peuvent utiliser la commande notation ship pour publier leur documentation sur Notion, où elle bénéficie de toutes les fonctionnalités de Notion, y compris l'IA, la recherche et le formatage.
Notation offre également des options de déploiement flexibles, permettant aux équipes de garder leur documentation interne, de la partager comme une page Notion publique, ou de la déployer comme un site web complet avec des services comme super.so.
En résumé, Notation est un outil puissant pour les équipes de développement qui cherchent à simplifier et à améliorer la gestion de leur documentation technique, tout en tirant parti des avantages de Notion.
