Das Linux Foundation-Projekt

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:

The Linux Foundation

Technischer Redakteur:

Bor

Projektname:

Die Dokumentation für das Hosting und die Generierung überarbeiten und die Einstiegsseiten und Entwicklerleitfäden neu strukturieren

Projektdauer:

Standardlaufzeit (3 Monate)

Projektbeschreibung

Zusammenfassung :

Eine Dokumentation soll Endnutzern und Entwicklern bei der Verwendung eines Produkts oder Dienstes helfen. Eine gute Dokumentation ist sehr wichtig, da sie Nutzern die Möglichkeit bietet, die Verwendung einer Software, ihre Funktionen, Tipps und Tricks zu erlernen und auch häufige Probleme bei der Verwendung der Software zu beheben. Außerdem werden dadurch 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 weiß der Nutzer möglicherweise nicht, wie er die oben genannten Dinge effektiv und effizient erledigen kann. 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 und eine gute Dokumentation diese Kommunikation in ein überschaubares Rahmenwerk stellt, auf das alle für den Erfolg zugreifen können.

Jede Dokumentationswebsite erfordert eine gute Workflow-Pipeline für den Aufbau und das Hosting. In einer Organisation wie AGL mit mehreren Versionen und einer umfangreichen Dokumentation sind die Dokumentationsdateien (Markdowns) auf mehrere Repositories verteilt, was die Verwaltung und Aktualisierung dieser Dateien extrem komplex und zeitaufwändig macht.

Aktueller Status :

• Die AGL Doc-Website basiert auf einer Sammlung von Markdown-Dateien, die aus verschiedenen Repositories abgerufen wurden.
• Die Dokumentseiten werden derzeit in den einzelnen Quellen als Markdown mit der Engine des Cordova-Projekts gehostet.
• Das führt zu einer Einrichtung von vier Repositories für den Build- und Hostingprozess 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 Erstellen einer technischen Website aus Markdown-Dateien.
• Docs-sources [https://github.com/automotive-grade-linux/docs-sources] : Quellcode (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-Seiten-Repository für die Dokumentationswebsite [https://gist.github.com/growupboron/docs.automotivelinux.org].
• Ein Tool (Script) 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 Erstellung von Websites für die Agl-Dokumentation : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
• Der Abschnitt section_version.yml enthält die Links zu allen YAML-Dateien des Buchs. Nun werden alle YAML-Dateien des Buchs aus Remote-Repositories in der docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] abgerufen. Die YAML-Dateien des Buchs enthalten alle URLs zu Ihren Markdown-Dateien aus dem Remote-Repository.
• Sobald alle Markdown-Dateien abgerufen wurden, generieren die Tools die AGL-Dokumentwebsite in docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages], die dann entsprechend bereitgestellt wird.
• Der aktuelle Prozess der Wartung der Pipeline ist nicht nutzerfreundlich und entwicklerfreundlich, insbesondere für neue Beitragende. Diese Workflow-Pipeline (für das Erstellen und Hosten) kann so vereinfacht und optimiert werden, dass sich die Entwickler auf die Dokumentation konzentrieren können, anstatt die Dokumentationserstellung und den Bereitstellungs-Workflow beizubehalten.