Notation

Notation ist ein leistungsstarkes Befehlszeilen-Interface (CLI)-Tool, das für Entwickler entwickelt wurde, die ihre Dokumentation neben ihrem Code pflegen möchten. Es schließt die Lücke zwischen dem Schreiben von Dokumentation in einem einfachen, universellen Format wie Markdown und der Veröffentlichung auf einer vielseitigen, kollaborativen Plattform wie Notion. Die Kernphilosophie hinter Notation ist, dass Dokumentation mit dem Code leben sollte, den sie beschreibt, den gleichen Überprüfungsprozessen unterliegen und einfach zu aktualisieren sein sollte, ohne sich bei separaten Diensten anzumelden. Es eliminiert die Komplexität der Verwaltung separater Dokumentations-Websites oder des Kampfes mit Frontend-Frameworks und bietet einen optimierten, entwicklerzentrierten Arbeitsablauf.

Durch die Verwendung von Notation können Teams sicherstellen, dass ihre Dokumentation immer auf dem neuesten Stand ihrer Codebasis ist. Wenn Code zusammengeführt wird, kann die entsprechende Dokumentation mit einem einzigen Befehl in Notion veröffentlicht werden. Dies macht die Dokumentation nicht nur für andere Ingenieure zugänglich, sondern auch für nicht-technische Teammitglieder wie Produktmanager, Designer und Support-Mitarbeiter, die mit der Verwendung von Notion vertraut sind. Das Tool nutzt alle nativen Funktionen von Notion, einschließlich seiner leistungsstarken Suche, KI-Fähigkeiten, reichhaltigen Formatierung und flexiblen Freigabeoptionen, und bietet so ein robustes Dokumentationssystem kostenlos.

Wie man Notation verwendet

Die Verwendung von Notation umfasst einen unkomplizierten Einrichtungsprozess, der Ihre lokale Entwicklungsumgebung mit Ihrem Notion-Arbeitsbereich integriert:

1. Installation: Installieren Sie das Notation-Binary mit einem einfachen curl-Befehl aus der offiziellen Dokumentation auf Ihrem lokalen Rechner. Dadurch wird der Befehl `notation` in Ihrem Terminal verfügbar.
2. Konfiguration: Erstellen Sie eine Konfigurationsdatei mit dem Namen `Notation.toml` im Verzeichnis `~/.notation/`. Diese Datei speichert Ihr Notion-API-Geheimnis und den Namen der übergeordneten Seite in Notion, auf der Sie Ihre Dokumentation veröffentlichen möchten.
3. Notion-Integration: Sie müssen eine neue interne Integration in Ihrem Notion-Arbeitsbereich erstellen. Dadurch wird ein geheimer API-Schlüssel generiert, den Sie Ihrer `Notation.toml`-Datei hinzufügen.
4. Mit Seite verbinden: Navigieren Sie in Notion zu der Seite, die Sie als übergeordnete Seite festgelegt haben. Verwenden Sie das Menü 'Verbindungen', um Ihrer neu erstellten Integration Zugriff auf diese Seite zu gewähren.
5. Dokumentation schreiben: Schreiben Sie Ihre Dokumentation in Markdown-Dateien im Repository Ihres Projekts. Sie können Dateien in Verzeichnissen organisieren, die Notation in verschachtelte Unterseiten in Notion umwandelt.
6. Veröffentlichen: Führen Sie den Befehl `notation ship --src ` in Ihrem Terminal aus. Notation analysiert Ihre Markdown-Dateien und die Verzeichnisstruktur und erstellt oder aktualisiert dann automatisch die entsprechenden Seiten in Ihrem Notion-Arbeitsbereich.

Kernfunktionen von Notation

• Markdown-zu-Notion-Konvertierung: Konvertiert Standard-Markdown-Dateien automatisch in schön formatierte Notion-Seiten. Es unterstützt Überschriften, Listen, Codeblöcke, Tabellen, Links und mehr.
• Beibehaltung der Verzeichnisstruktur: Repliziert Ihre lokale Verzeichnisstruktur als verschachtelte Seiten in Notion und erleichtert so die Organisation komplexer Dokumentation.
• CLI-basierter Arbeitsablauf: Integriert sich nahtlos in die Befehlszeilenumgebung des Entwicklers und kann zu CI/CD-Pipelines für automatisierte Dokumentationsaktualisierungen hinzugefügt werden.
• Benutzerdefinierte Seitenmetadaten: Ermöglicht es Ihnen, den Notion-Seitentitel und das Emoji-Symbol direkt aus Ihrer Markdown-Datei mit einfachen Flags wie `--title "Meine Seite"` und `--emoji 🚀` festzulegen.
• Inhalt der übergeordneten Seite: Eine spezielle `intro.md`-Datei kann verwendet werden, um Inhalte direkt zur Haupt-Elternseite hinzuzufügen, anstatt eine separate Unterseite zu erstellen.
• Nutzung der Leistungsfähigkeit von Notion: Nach der Veröffentlichung profitiert die Dokumentation von der erweiterten Suche, den integrierten KI-Funktionen, der kollaborativen Bearbeitung und den flexiblen Freigabeoptionen von Notion (intern, öffentlich oder als Website).
• Handhabung relativer Links: Konvertiert relative Links zwischen Markdown-Dateien intelligent in korrekte Notion-Seitenlinks und gewährleistet so eine nahtlose Navigation innerhalb Ihrer Dokumentation.

Anwendungsfälle für Notation

Notation ist vielseitig und kann für verschiedene Dokumentationsanforderungen angepasst werden:

• Interne Engineering-Wikis: Erstellen und pflegen Sie eine zentralisierte Wissensdatenbank für Ihr Entwicklungsteam, wobei die Dokumentation direkt neben dem relevanten Code liegt.
• Öffentliche API-Dokumentation: Veröffentlichen Sie klare, gut strukturierte API-Dokumentation für externe Entwickler. Die Notion-Seite kann mit einem einzigen Klick öffentlich gemacht werden.
• Benutzerhandbücher und Anleitungen: Entwickeln Sie benutzerorientierte Dokumentation, zu der nicht-technische Autoren leicht beitragen können (über Notion) und die Entwickler leicht aktualisieren können (über Markdown).
• Projektdokumentation: Halten Sie alle projektbezogenen Dokumente, von technischen Spezifikationen bis hin zu Besprechungsnotizen, organisiert und synchron mit dem Entwicklungslebenszyklus des Projekts.
• Persönliche Wissensdatenbank: Entwickler können es verwenden, um ihre persönlichen Notizen und technischen Referenzen zu verwalten und sie in einem privaten Notion-Bereich zu veröffentlichen.

Vorteile von Notation

Der Hauptvorteil von Notation ist seine Einfachheit und sein entwicklerorientierter Ansatz.

• Dokumentation als Code: Indem Dokumente im Repository aufbewahrt werden, können sie als Teil des Standard-Entwicklungs-Workflows versioniert, überprüft und aktualisiert werden.
• Reduzierter Aufwand: Eliminiert die Notwendigkeit, komplexe statische Seitengeneratoren wie Docusaurus zu verwalten und bereitzustellen oder Frontend-Frameworks wie React zu lernen.
• Einzige Quelle der Wahrheit: Stellt sicher, dass die Dokumentation in Notion eine direkte Widerspiegelung der Markdown-Dateien im Repository ist und verhindert so Inhaltsabweichungen.
• Verbesserte Zugänglichkeit: Macht technische Dokumentation für Nicht-Ingenieure leicht zugänglich und lesbar und fördert eine bessere funktionsübergreifende Zusammenarbeit.
• Kosteneffizient: Das Tool selbst ist kostenlos und Open Source und nutzt die kostenlosen oder bestehenden Stufen von Notion, was es zu einer sehr wirtschaftlichen Lösung macht.

Preise und Pläne

Notation ist ein kostenloses Open-Source-Tool. Es steht kostenlos zum Download und zur Nutzung zur Verfügung. Benutzer unterliegen nur den Kosten, die mit ihrem Notion-Plan verbunden sind (viele Anwendungsfälle können mit dem kostenlosen Plan von Notion abgedeckt werden) oder etwaigen Drittanbieterdiensten, die sie möglicherweise nutzen, um ihre Notion-Seite in eine Website mit benutzerdefinierter Domain umzuwandeln, wie z. B. super.so.