Von Confluence auf Metalsmith - Eine Geschichte über die Migration von Nuxeo-Dokumenten

Haben Sie letzte Woche die großen Veränderungen auf unserer Dokumentationsseite bemerkt? Wenn nicht, unterbrechen Sie kurz Ihre Arbeit und werfen Sie gleich einen Blick darauf. Es lohnt sich! Nach mehreren Monaten Arbeit freuen wir uns wirklich, dass eine völlig überarbeitete und brandneue Nuxeo-Dokumentationsseite live gegangen ist! VORHER NACHHER Es ist nicht nur ein Update im Erscheinungsbild. Wir haben das Dokumentationstool selbst geändert und Confluence durch eine statische Webseite ersetzt, die mit Metalsmith erstellt wurde. Heute sprechen wir darüber, warum wir uns zu dieser Migration entschieden haben, und wie wir die Metalsmith-Plug-in-Umgebung verbessert haben. ## Was steckt hinter der Generierung einer statischen Website mit Metalsmith? Die neue Dokumentationswebsite ist eine Zusammenstellung aus Textinhalten und graphischen Ressourcen, die durch eine Reihe von Transformationen geleitet wird, um das gewünschte Erscheinungsbild und Links zu erstellen. Metalsmith übernimmt diese Weiterleitung in JavaScript. Dabei können zusätzliche Weiterleitungen hinzugefügt werden, etwa eine, die alle {page page='my-page' space='NXDOC'} durch einen gewünschten Link auf eine bestimmte Seite ersetzt. Quellen der Webseite werden auf GitHub festgelegt. ## Warum haben wir Confluence aufgegeben & welche Vorteile ergeben sich für uns mit Metalsmith? Confluence war ein tolles Tool, als wir mit unserer Dokumentationswebsite begonnen haben. Es war sehr benutzerfreundlich und Seiten konnten einfach erstellt, aktualisiert und gepflegt werden. Seit einigen Monaten kam es jedoch zu Einschränkungen, weshalb wir uns letztlich zur Migration entschieden haben. Dies sind die Gründe dafür: - Bessere Kontrolle über das allgemeine Layout eines Dokuments: Am dringendsten war für uns die Vereinfachung der Dokumentation durch eine schlichtere und reaktivere Website, um die Navigation zwischen Seiten zu verbessern, selbst wenn diese nicht am gleichen Ort gespeichert sind oder aus unterschiedlichen Versionen bestehen. In Confluence gab es ein paar Möglichkeiten, Vorlagen zu verändern, aber es verhielt sich ziemlich proprietär: es erforderte Übermittlungen und es mussten stets Versionen migriert werden. - Bessere Kontrolle bei der Verlinkung der gleichen Seiten für verschiedene Versionen des Produkts: Jedes Jahr wird eine neue Hauptversion der Nuxeo Content Services Platform veröffentlicht. Es ist möglich, die gesamte Dokumentation einer bestimmten Version zu durchsuchen, es kann jedoch auch hilfreich sein, den entsprechenden Inhalt einer früheren Version der gleichen Seite abrufen zu können. Auf der alten Dokumentationswebsite war dies nicht so leicht möglich. Wir konnten dies nun mithilfe automatisierter Linkerstellung einfach umsetzen. Wir haben außerdem die Möglichkeit, einen Ausweichlink hinzuzufügen, wenn es keine entsprechende Seite gibt oder das Konzept geändert wurde. - SEO-Verhalten: Da wir die volle Kontrolle über den HTML-Content der Seite besitzen, können wir alle erforderlichen Überschriften für die Suchmaschinenoptimierung bereitstellen, was für uns entscheidend ist. Dies war früher nicht möglich. - Eine bessere Benutzererfahrung bei der Erstellung von Content (nativer Markdown-Support und bessere Kontrolle über Seiteninhalte mit hervorragenden Content-Editoren): Markdown kann über eine Erweiterung von Confluence hinzugefügt werden, was früher nicht möglich war. Die Wiki-Syntax von Confluence ist relativ proprietär, was für unsere Entwickler nicht optimal ist, da sie üblicherweise die Dokumentation schreiben. Mit einfachen Markdownseiten muss nicht mehr auf die “html-Quelle” gewechselt werden! Außerdem ist das Schreiben von Content mit Atom.io oder Sublime wesentlich angenehmer. Die neue Website ist im Grunde genommen ein Ordner mit Textdateien, den wir unter anderem offline bearbeiten, Massensuchen durchführen und alle Dateien auf einmal ersetzen können. - Besseres Prozessmanagement und Qualitätsprüfungen: Wir haben Funktionen wie die Überprüfung von Daten, Seitenstatus usw. implementiert, um Prozesse zu verwalten. Das Hinzufügen von Qualitätsprüfungen (für Seitensyntax, fehlerhafte Links usw.) ist relativ einfach. Wir haben einige dieser Prüfungen integriert und möchten in naher Zukunft weitere hinzufügen. - Die Kollaboration mit GitHub funktioniert fantastisch: Es ist einfach cool, einen Zweig für jede Modifizierung, Pull-Anforderungen, Commit-Verlauf usw. abrufen zu können. ## Funktionen, die den Bare Metalsmith-Generatoren hinzugefügt wurden Wenn Sie sich die Dokumentation über Metalsmith durchlesen, werden Sie schnell feststellen, dass alles in Metalsmith über Plug-ins verwaltet wird. Deshalb haben wir alle Funktionen aufgelistet, die wir von Confluence übernehmen wollten, und haben für jede von ihnen ein Plug-in erstellt. Zum Beispiel: - Auszug - Mehrfachauszug - Tag - Verlauf - Seitenlinks - Linkes Menü - Warnungen bei Seitenüberprüfungen - Seitenlinks Wir haben zusätzlich neue Plug-ins für Funktionen erstellt, die in Confluence nicht verfügbar waren. Für die Versionierung können wir beispielsweise Seiten selbst dann verlinken, wenn diese zwischen zwei Versionen umbenannt wurden. Wir haben außerdem einen Überprüfungsprozess für die Dokumentation implementiert. Am allerwichtigsten ist, dass die Website in Metalsmith mehr Möglichkeiten für die Überprüfung von Content, Layout, Grafikdesign und Beiträgen bietet. ## Migration des Contents Wir haben die REST API von Confluence für die Migration des Contents verwendet und mithilfe einiger Transformationen auf Markdown konvertiert. Außerdem haben wir alles Unnütze aussortiert (einschließlich der Erstellung kurzer Links, Verlaufszusammenfassung, letzter Autor, Tags usw.). ## Wie geht es weiter? Das war erst der Anfang unseres Projekts! Wir arbeiten bereits an der zweiten Version der Dokumentationswebsite, die eine bessere Navigation, Grafik und ein besseres Design aufweist. Da Nuxeo schnell wächst, muss die Dokumentation entsprechend mitwachsen, um den stets steigenden Bedürfnissen gerecht zu werden. Wir hoffen, dass Sie sich dadurch besser bei Nuxeo zurechtfinden, unsere Produkte detailliert kennenlernen, mehr Dokumentationen lesen und einen Beitrag zu Nuxeo leisten können. Sagen Sie uns, was Sie von dieser neuen Website halten. Sollten Sie sogar daran interessiert sein, die von uns geschriebenen Plug-ins für Metalsmith zu verwenden, dann machen Sie sich mit GitHub vertraut :) Wir freuen uns über Ihr Feedback und Ihre Verbesserungsvorschläge! Es kommt noch mehr dazu - bleiben Sie also dran, um weitere Neuigkeiten zu erfahren!