Das Linux Foundation-Projekt

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:
Die Linux Foundation
Technischer Redakteur:
Bron
Projektname:
Die Dokumentation zum Hosten und Erstellen der Dokumentation sowie die Startseiten und Entwicklerleitfäden neu strukturieren.
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

Zusammenfassung :

Eine Dokumentation soll Endnutzer und Entwickler bei der Verwendung eines Produkts oder Dienstes unterstützen. Eine gute Dokumentation ist sehr wichtig, da sie Nutzenden die Möglichkeit bietet, die Verwendung einer Software zu erlernen, ihre Funktionen, Tipps und Tricks zu lernen und häufige Probleme zu lösen, die bei der Verwendung der Software auftreten. Sie senkt auch die Supportkosten und ist Teil der Unternehmens- und Open-Source-Identität des Produkts : Eine gute Dokumentation ist ein Zeichen für die Integrität des Produkts und des Entwicklerteams.

Ohne eine gute Dokumentation wissen Nutzende 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 gute Kommunikation im Mittelpunkt jedes Unternehmens oder Produkts steht und immer sein wird. Eine gute Dokumentation fügt diese Kommunikation einfach in ein überschaubares Framework ein, auf das jeder Zugriff hat, um erfolgreich zu sein.

Jede Dokumentationswebsite benötigt eine gute Erstellungs- und Hosting-Workflow-Pipeline. In einem Unternehmen wie AGL mit mehreren Versionen und einer umfangreichen, ausführlichen Dokumentation sind die Dokumentationsdateien (Markdowns) auf mehrere Repositories verteilt, was die Aufgabe der Pflege und Aktualisierung extrem komplex und zeitintensiv macht.

Aktueller Status :

  • Die AGL-Dokument-Website basiert auf einer Sammlung von Markdown-Dateien, die aus verschiedenen Repositories abgerufen wurden.
  • Die Dokumentseiten werden derzeit in den einzelnen Quellen als Markdown gehostet, indem die Engine des Cordova-Projekts verwendet wird.
  • Dies führt zu einer Einrichtung mit vier Repositories für den Dokumentations-Build und den Hosting-Prozess :
  • 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] : 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] : Bereitstellung des GitHub-Seiten-Repositorys für die Dokumentationswebsite [https://gist.github.com/growupboron/docs.automotivelinux.org].
  • Ein Tool (Script), das in docs-tools [https://github.com/automotive-grade-linux/docs-tools] verfügbar ist, übernimmt das Sammeln und 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 bei der Erstellung von agl-Dokumentationswebsites : 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 Buch-YAML-Dateien aus Remote-Repositories in die docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] abgerufen. Die YAML-Dateien für das Buch enthalten alle URLs zu Ihren Markdown-Dateien aus dem Remote-Repository.
  • Sobald alle Markdown-Dateien abgerufen wurden, wird mit den Tools die Website des AGL-Dokuments auf den docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] erstellt, die entsprechend bereitgestellt wird.
  • Der aktuelle Wartungsprozess der Pipeline ist nicht benutzerfreundlich und entwicklerfreundlich, insbesondere für neue Beitragende. Diese Workflow-Pipeline (Erstellung und Hosting) kann vereinfacht und optimiert werden, sodass sich Entwickler besser auf die Dokumentation konzentrieren können, anstatt den Workflow zur Dokumentationsgenerierung und -bereitstellung zu verwalten.