Notation

Notation est un puissant outil d'interface en ligne de commande (CLI) conçu pour les développeurs qui souhaitent maintenir leur documentation à côté de leur code. Il comble le fossé entre l'écriture de la documentation dans un format simple et universel comme le Markdown et sa publication sur une plateforme polyvalente et collaborative comme Notion. La philosophie fondamentale de Notation est que la documentation doit vivre avec le code qu'elle décrit, être soumise aux mêmes processus de révision et être facile à mettre à jour sans se connecter à des services distincts. Il élimine la complexité de la gestion de sites de documentation séparés ou de la lutte avec des frameworks front-end, offrant un flux de travail simplifié et centré sur le développeur.

En utilisant Notation, les équipes peuvent s'assurer que leur documentation est toujours à jour avec leur base de code. Lorsque le code est fusionné, la documentation correspondante peut être publiée sur Notion avec une seule commande. Cela rend la documentation accessible non seulement aux autres ingénieurs, mais aussi aux membres de l'équipe non techniques comme les chefs de produit, les concepteurs et le personnel de support qui sont à l'aise avec Notion. L'outil exploite toutes les fonctionnalités natives de Notion, y compris sa recherche puissante, ses capacités d'IA, son formatage riche et ses options de partage flexibles, offrant un système de documentation robuste gratuitement.

Comment utiliser Notation

L'utilisation de Notation implique un processus de configuration simple qui intègre votre environnement de développement local à votre espace de travail Notion :

1. Installation : Installez le binaire de Notation sur votre machine locale à l'aide d'une simple commande curl fournie dans la documentation officielle. Cela rend la commande `notation` disponible dans votre terminal.
2. Configuration : Créez un fichier de configuration nommé `Notation.toml` dans le répertoire `~/.notation/`. Ce fichier stockera votre secret d'API Notion et le nom de la page parente dans Notion où vous souhaitez publier votre documentation.
3. Intégration Notion : Vous devez créer une nouvelle intégration interne dans votre espace de travail Notion. Cela générera une clé API secrète que vous ajouterez à votre fichier `Notation.toml`.
4. Connexion à la Page : Dans Notion, accédez à la page que vous avez désignée comme page parente. Utilisez le menu 'Connexions' pour accorder à votre intégration nouvellement créée l'accès à cette page.
5. Écrire la Documentation : Rédigez votre documentation dans des fichiers Markdown au sein du dépôt de votre projet. Vous pouvez organiser les fichiers dans des répertoires, que Notation convertira en sous-pages imbriquées dans Notion.
6. Publier : Exécutez la commande `notation ship --src ` dans votre terminal. Notation analysera vos fichiers Markdown et votre structure de répertoires, puis créera ou mettra à jour automatiquement les pages correspondantes dans votre espace de travail Notion.

Fonctionnalités principales de Notation

• Conversion de Markdown en Notion : Convertit automatiquement les fichiers Markdown standard en pages Notion magnifiquement formatées. Il prend en charge les en-têtes, les listes, les blocs de code, les tableaux, les liens, et plus encore.
• Préservation de la Structure des Répertoires : Réplique votre structure de répertoires locale en tant que pages imbriquées dans Notion, facilitant l'organisation de la documentation complexe.
• Flux de Travail Basé sur la CLI : S'intègre de manière transparente dans l'environnement de ligne de commande du développeur et peut être ajouté aux pipelines CI/CD pour des mises à jour de documentation automatisées.
• Métadonnées de Page Personnalisées : Vous permet de définir le titre de la page Notion et l'icône emoji directement depuis votre fichier Markdown à l'aide de simples indicateurs comme `--title "Ma Page"` et `--emoji 🚀`.
• Contenu de la Page Parente : Un fichier spécial `intro.md` peut être utilisé pour ajouter du contenu directement à la page parente principale, plutôt que de créer une sous-page distincte.
• Exploite la Puissance de Notion : Une fois publiée, la documentation bénéficie de la recherche avancée de Notion, des fonctionnalités d'IA intégrées, de l'édition collaborative et des options de partage flexibles (interne, public ou en tant que site web).
• Gestion des Liens Relatifs : Convertit intelligemment les liens relatifs entre les fichiers Markdown en liens de page Notion appropriés, assurant une navigation fluide au sein de votre documentation.

Cas d'utilisation pour Notation

Notation est polyvalent et peut être adapté à divers besoins de documentation :

• Wikis d'Ingénierie Internes : Créez et maintenez une base de connaissances centralisée pour votre équipe de développement, avec la documentation vivant juste à côté du code pertinent.
• Documentation d'API Publique : Publiez une documentation d'API claire et bien structurée pour les développeurs externes. La page Notion peut être rendue publique en un seul clic.
• Guides et Manuels d'Utilisation : Développez une documentation destinée aux utilisateurs, facile à contribuer pour les rédacteurs non techniques (via Notion) et à mettre à jour pour les développeurs (via Markdown).
• Documentation de Projet : Gardez tous les documents liés au projet, des spécifications techniques aux notes de réunion, organisés et synchronisés avec le cycle de vie du développement du projet.
• Base de Connaissances Personnelle : Les développeurs peuvent l'utiliser pour gérer leurs notes personnelles et leurs références techniques, en les publiant dans un espace Notion privé.

Avantages de Notation

Le principal avantage de Notation est sa simplicité et son approche axée sur le développeur.

• Documentation en tant que Code : En gardant les documents dans le dépôt, ils peuvent être versionnés, révisés et mis à jour dans le cadre du flux de travail de développement standard.
• Réduction des Frais Généraux : Élimine le besoin de gérer et de déployer des générateurs de sites statiques complexes comme Docusaurus ou d'apprendre des frameworks front-end comme React.
• Source Unique de Vérité : Garantit que la documentation dans Notion est un reflet direct des fichiers Markdown dans le dépôt, empêchant la dérive du contenu.
• Accessibilité Améliorée : Rend la documentation technique facilement accessible et lisible pour les non-ingénieurs, favorisant une meilleure collaboration interfonctionnelle.
• Rentable : L'outil lui-même est gratuit et open-source, et il exploite les niveaux gratuits ou existants de Notion, ce qui en fait une solution très économique.

Tarification et plans

Notation est un outil gratuit et open-source. Il est disponible en téléchargement et à l'utilisation sans frais. Les utilisateurs ne sont soumis qu'aux coûts associés à leur plan Notion (de nombreux cas d'utilisation peuvent être servis par le plan gratuit de Notion) ou à tout service tiers qu'ils pourraient utiliser pour transformer leur page Notion en un site web avec un domaine personnalisé, tel que super.so.