Docs as Code bei Linode

Hi! Mein Name ist Nathan, ich bin Mitglied des Technical Writing Teams von Linode. Eine unserer Hauptaufgaben ist es, die Bibliothek der Guides und Tutorials auf https://www.linode.com/docs, in der bereits über 1400 Artikel veröffentlicht wurden, zu pflegen und zu erweitern. Um eine hohe Qualität der Inhalte zu gewährleisten und die Zusammenarbeit im Schreibprozess zu fördern, haben wir die Docs as Code-Methode für unseren Authoring-Workflow eingeführt.

Docs as Code ist eine Methode, bei der die Werkzeuge für das Schreiben von Dokumentation die gleichen sind wie die Werkzeuge, die zum Schreiben von Software verwendet werden. Dazu gehören:

• Der Einsatz von Versionskontrollsoftware
• Schreiben von Klartext-Dokumentationen
• Das Ausführen von automatisierten Tests
• Kontinuierliche Integration und kontinuierliche Lieferung

Das Technical Writing Team von Linode hat diese Methodik zudem erweitert, indem es die Verantwortung für die Cloud-Infrastruktur übernommen hat, die unsere docs-Website hostet.

Warum Docs as Code?

Die Einhaltung dieser Praktiken bietet eine Reihe von Vorteilen:

• Die Arbeit mit diesen Technologien trägt dazu bei, eine engere Verbindung zwischen dem Technical Writing Team und den Entwicklungs- und Konstruktionsteams von Linode herzustellen.
  
• Andere Teams bei Linode können zu verschiedenen Aspekten unseres Prozesses beitragen. Zum Beispiel: Das Front End Team kann bei der Aktualisierung der Themen und ihrer Präsentation auf der docs-Website mit denselben Tools, mit denen es bereits arbeitet, helfen. Ein Mitglied des Engineering-Teams könnte andererseits neue automatisierte Tests für die docs-Bibliothek schreiben.
  
• Unser Team schreibt häufig Anleitungen und Tutorials über die in unserem Prozess verwendeten Technologien. Wenn wir diese für uns selbst einsetzen, verstehen wir sie besser und können sie besser erklären.
  
• Wir müssen auch die Produkte von Linode genau dokumentieren, was auch die Überprüfung der Codebase von Linode beinhalten kann. Wenn wir die für diese Projekte verwendeten Sprachen und Tools fließend beherrschen, können wir sie besser verstehen.

Unsere Implementierung

Da die Implementierungen dieser Methodik von Unternehmen zu Unternehmen unterschiedlich sein können, möchte ich hier einen detaillierten Überblick über unseren Prozess geben:

1. Authoring: Unsere technischen Redakteure verfassen neue Leitfäden in Markdown. Markdown wird zur Darstellung von Rich Text in einer reinen Textdatei verwendet und kann mit einer Reihe von Werkzeugen in HTML kompiliert werden. Markdown ist in der Software-Entwicklung nahezu universell einsetzbar; so werden beispielsweise GitHub README-Dateien in Markdown geschrieben. In Markdown zu schreiben bedeutet auch, dass Sie jeden Plain Text Editor benutzen können, von modernen Desktop-Editoren wie Visual Studio Code bis hin zu Emacs und Vim. Wir wissen, dass die Leute ihre bevorzugten Text-Editoren lieben, und diese Flexibilität hilft mehr Leuten, zu unserer Bibliothek beizutragen.
   
2. Seitenvorschau: Die Markdown Files in unserer Bibliothek werden erstellt mit einem statischen Site Generator. Statische Sites sind Sammlungen von vorgefertigten Seiten, die nicht auf eine Datenbank angewiesen sind, um gerendert zu werden (wie es bei einem CMS wie WordPress der Fall ist). Aus diesem Grund ist eine statische Seite sehr schnell zu laden. Ein statischer Website-Generator rendert eine statische Website, indem er Ihre Inhaltsdateien (z.B. Markdown) mit einem von Ihnen festgelegten Theme kombiniert.
   
   Linodes docs-Website verwendet Hugo, der einer der beliebteste statischen Site-Generators ist::
   
   • Hugo bietet gut dokumentierte Installationsmethoden für viele Betriebssysteme, so dass es keine Probleme bei der Einarbeitung eines neuen Mitarbeiters gibt.
     
   • Hugo beinhaltet einen lokalen Development-Webserver, so dass Autoren die Website auf ihren Computern rendern können, während sie neue Anleitungen schreiben. Dieser Server wird sich umgehend reloaden, sobald der Autor seine Datei speichert.
     
   • Hugo ist extrem schnell, was für eine Bibliothek unserer Größe ein bedeutender Faktor ist - mein Macbook Pro ist in der Lage, alle 1400 Anleitungen in ca. drei Sekunden darzustellen, die Live-Reload-Funktion arbeitet fast in Echtzeit. 
     
   • Hugos Shortcodes helfen uns zudem dabei, unsere Guides mit Funktionen zu erweitern, die Markdown sich nicht leisten kann, einschließlich hervorgehobener Notizen und zeilennummerierter Codeschnipsel.
     
     
3. Collaboration: Die docs-Bibliothek ist in einem öffentlichen Git-Repository auf GitHub abgelegt. Jeder Autor unterhält einen Fork dieses Repositorys. Wenn ein Autor mit dem Entwurf eines Leitfadens fertig ist, übergibt er seine Änderungen, schiebt sie bis zu seinem Fork und öffnet dann eine Pull-Anfrage im Haupt-Repository.
   
   Unser Schreibprozess sieht zwei getrennte Teammitglieder vor, die eine technische Bearbeitung und dann eine Textbearbeitung für alle neuen Guides oder Guide-Updates durchführen. Diese Teammitglieder werden den Branch der Pull-Anfrage herunterladen, ihre Änderungen vornehmen und das Ganze dann wieder auf GitHub zurückschieben. Git ist ein weiteres nahezu universelles Werkzeug für die Entwicklung, sein Einsatz ermöglicht es uns, einige standardmäßige Best Practices für die Zusammenarbeit zu nutzen, wie den gitflow-Workflow.
   
   Außerdem führt die Popularität von GitHub dazu, dass es eine große Anzahl von nützlichen Integrationen gibt. Insbesondere setzen wir Netlify ein, um für jeden Pull-Request eine automatische, öffentlich zugängliche Vorschau zu generieren. Wir fragen oft nach Feedback von Linodianern in verschiedenen Abteilungen, und sie können diese gemeinsam nutzbaren Netlify-Links ansehen, ohne unser Dokument-Repository klonen und Hugo auf ihren Laptops installieren zu müssen.
   
   Schließlich öffnet das Hosting in einem öffentlichen Repository unsere Bibliothek für externe Mitwirkende, was wir begrüßen.
   
4. Testing: Immer wenn ein Pull-Request (PR) gestellt oder aktualisiert wird, wird eine Reihe von Tests des PR-Inhalts durchgeführt. Diese Tests werden durchgeführt mit Travis CI, ein kontinuierlicher Integration Service, der auch die GitHub Integration anbietet. Wenn einer dieser Tests fehlschlägt, wird der Pull-Request vorübergehend für die Zusammenführung gesperrt:
   
   • Der Inhalt von Leitfäden wird auf Rechtschreibung und Stil (z.B. korrekte Groß- und Kleinschreibung von Fachbegriffen) geprüft. Für diese Aufgaben verwenden wir Vale, ein Open Source Linter, der für die Arbeit an Prosa konzipiert ist. Als wir Vale zum ersten Mal anwendeten, wurden über 500.000 Rechtschreibfehler in unserer Bibliothek gemeldet. Es war zwar etwas peinlich, aber die Kenntnis dieser Zahl und die Möglichkeit, darauf zu reagieren, hat uns einen großen Vertrauensschub in unsere Inhalte und in unser neues Publikationssystem gegeben.
     
   • Wir prüfen auf mögliche Broken Links zwischen den Guides mit Hilfe von Scrapy, einem Open Source Python-Framework, das Inhalte von Webseiten untersucht. Dieser Test wurde in Zusammenarbeit mit einem Mitglied des Ingenieurteams von Linode geschrieben. Bei der ersten Implementierung von Scrapy fanden wir eine Reihe von defekten Links, die wir korrigieren konnten.
     
   • Ein weiteres Python-Skript prüft, ob die Front Matter-Metadaten für Guides gültig und frei von Syntaxfehlern sind. Ein defekter Front Matter-Abschnitt kann Probleme beim Aufbau der Website verursachen, so dass wir durch die Validierung sicher sein können, dass die Website bei der Aktualisierung der Produktions-Webserver gerendert wird.
     
5. Veröffentlichung und Hosting: Die Aktualisierung der docs-Website wird automatisch durch eine Sammlung von Skripten durchgeführt, die durch bestimmte Events auf GitHub ausgelöst werden:
   
   • Immer wenn Inhalte in den Master-Branch des Haupt-Docs Repositories eingebunden werden, wird eine Webhook-Benachrichtigung an einen Staging-Webserver - eine Linode-Instanz - gesendet. Dieser Staging-Webserver zieht dann den Master-Branch von GitHub und baut die Site mit Hugo auf, mit dem Document Root des Webservers als Ziel für die gerenderte Site. Wir sehen uns diese Staging-Website an und bestätigen, dass der Inhalt wie erwartet erscheint.
     
     Der Staging Server war anfangs nicht Teil unseres Workflows; er wurde ausgebaut, nachdem ein Zwischenfall unser CSS/Styling während eines Updates der Production Site vorübergehend unterbrochen hatte. Kurz gesagt: Netlify hatte eine Vorschau auf die neue Version der Website korrekt gerendert, aber es gelang nicht, ein Styling-Problem zu erkennen. Dies lag daran, dass unsere "Entwicklungs"-Build-Pipeline verwendet wurde, anstatt unserer "Produktions"-Build-Pipeline (die unser CSS und andere Vermögenswerte minimiert). Der neue Staging-Server wird mit der gleichen Konfiguration wie unser Produktionsserver eingerichtet, so dass er auch die Produktions-Build-Pipeline verwendet und Fehler wie diesen vermeiden wird.
     
   • Um die Production Site zu aktualisieren, erstellen wir einen neuen Release-Tag auf GitHub. Dies löst eine weitere Webhook-Benachrichtigung aus, die an den Produktionswebserver gesendet wird. Dieser Server führt ein Skript aus, das dem Staging-Server ähnlich ist, aber stattdessen zieht er den Inhalt aus dem neuen Release-Tag.
   • Wenn unsere Veröffentlichungsfunktion automatisch abläuft, werden menschliche Fehler, die bei einer manuellen Durchführung dieses Prozesses auftreten könnten, minimiert. Sowohl die Staging- als auch die Production-Server werden über Salt-Formeln konfiguriert, wodurch menschliche Fehler bei der Wartung oder Aktualisierung der Software minimiert werden. Salt wird auch bei anderen Infrastrukturprojekten in Linode eingesetzt, so dass unsere docs-Webserver leicht verwaltet werden können.

Die Anwendung dieser Methodik hat uns geholfen, unsere Arbeitsabläufe zu rationalisieren, aber wir wollen sie noch weiter verbessern. Wenn Sie Vorschläge für Updates haben, lassen Sie es uns wissen! Ich bin auf der Write the Docs Slack als "Nmelehan" unterwegs, wie mehrere andere Teammitglieder auch. Wenn Sie mehr über Docs als Code lesen möchten, würde ich Eric Holschers Anleitung auf der Write the Docs Website empfehlen.