Das Linux Foundation-Projekt

Diese Seite enthält die Details eines Projekts zum technischen Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:
The Linux Foundation
Technischer Redakteur:
boron
Projektname:
Rework the documentation hosting &generation and Restructure getting started pages and developer guides.
Projektlänge:
Standardlänge (3 Monate)

Projektbeschreibung

Zusammenfassung :

Eine Dokumentation soll Endnutzern und Entwicklern helfen, ein Produkt oder einen Dienst zu verwenden. Eine gute Dokumentation ist sehr wichtig, da sie Nutzern die Möglichkeit bietet, zu erfahren, wie sie eine Software verwenden, welche Funktionen sie hat und welche Tipps und Tricks es gibt. Außerdem können sie damit häufig auftretende Probleme lösen. Außerdem werden die Supportkosten gesenkt und die Dokumentation ist Teil der Unternehmens- und Open-Source-Identität des Produkts. Eine gute Dokumentation ist ein Zeichen für die Gesundheit des Produkts und des Entwicklerteams.

Ohne eine gute Dokumentation wissen Nutzer möglicherweise nicht, wie sie die oben genannten Dinge effektiv und effizient erledigen können. Dokumentationen können eine entscheidende Rolle für den Erfolg eines Produkts spielen, da eine gute Kommunikation immer im Mittelpunkt eines Unternehmens oder Produkts steht. Eine gute Dokumentation bietet einen übersichtlichen Rahmen, auf den alle zugreifen können, um erfolgreich zu sein.

Jede Dokumentationswebsite benötigt eine gute Workflow-Pipeline für die Erstellung und das Hosting. In einer Organisation wie AGL mit mehreren Versionen und einer umfangreichen Dokumentation sind die Dokumentationsdateien (Markdowns) auf mehrere Repositories verteilt. Das macht die Wartung und Aktualisierung unglaublich komplex und zeitaufwendig.

Aktueller Status :

  • Die AGL-Dokumentationswebsite basiert auf einer Sammlung von Markdown-Dateien aus verschiedenen Repositories.
  • Die Dokumentationsseiten werden derzeit in den einzelnen Quellen als Markdown mit der Engine des Cordova-Projekts gehostet.
  • Das führt zu einer Einrichtung mit vier Repositories für die Erstellung und das Hosting der Dokumentation :
  • Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : Enthält die Jekyll-Websitevorlage.
  • Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : Enthält Tools zum automatischen Generieren einer technischen Website aus Markdown-Dateien.
  • Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Quelle (Markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) für allgemeine Dokumente und Anleitungen.
  • Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : Bereitgestelltes GitHub-Repository für die Dokumentationswebsite [https://gist.github.com/growupboron/docs.automotivelinux.org].
  • Ein Tool (Skript) in „docs-tools“ [https://github.com/automotive-grade-linux/docs-tools] sammelt und erstellt Vorlagen für alle Markdown-Dateien gemäß der Datei „fetched_files.yml“ in „docs-webtemplate“ [https://github.com/automotive-grade-linux/docs-webtemplate].
  • Der aktuelle Workflow für die Generierung der AGL-Dokumentationswebsite : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
  • Die Datei „section_version.yml“ enthält die Links zu allen YAML-Dateien des Buchs. Anschließend werden alle YAML-Dateien des Buchs aus Remote-Repositories in „docs-webtemplate“ [https://github.com/automotive-grade-linux/docs-webtemplate] abgerufen. Die YAML-Dateien des Buchs enthalten alle URLs zu den Markdown-Dateien aus dem Remote-Repository.
  • Sobald alle Markdown-Dateien abgerufen wurden, werden mit den Tools die AGL-Dokumentationswebsite in „docs-gh-pages“ [https://github.com/automotive-grade-linux/docs-gh-pages] generiert und entsprechend bereitgestellt.
  • Der aktuelle Prozess zur Wartung der Pipeline ist nicht nutzer- und entwicklerfreundlich, insbesondere für neue Mitwirkende. Diese Workflow-Pipeline (für Erstellung und Hosting) kann vereinfacht und optimiert werden, damit sich Entwickler auf die Dokumentation konzentrieren können, anstatt den Workflow für die Generierung und Bereitstellung der Dokumentation zu verwalten.