Kolibri-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:

Kolibri

Technischer Redakteur:

StephDix

Projektname:

Regeln für den Stil und die Workflows der Kolibri-Ecosystem-Dokumentation

Projektdauer:

Lang andauernd (5 Monate)

Projektbeschreibung

Zusammenfassung

In diesem Dokument wird die Implementierung der Stilrichtlinien und des Workflow-Managements in den dokumentierten Informationen von Learning Equality für das Projekt „Kolibri Ecosystem“ erläutert.

Übersicht

Mein Vorschlag besteht aus vier Phasen. In der ersten Phase werde ich den LE Documentation Style Guide mit Leitlinien zur Barrierefreiheit, zum Schreiben und zum Formatieren gemäß den LE-Konzepten und Stilrichtlinien in der Softwareentwicklung abschließen. In der zweiten Phase führe ich eine Qualitätsüberprüfung der ReadTheDocs- und Google Docs-Dokumente durch. Der Analyseplan enthält Checklisten zur Bewertung der Einhaltung der Stilrichtlinien. Diese Checklisten helfen Ihnen, Ergebnisse zu dokumentieren und Änderungen an der Dokumentation vorzunehmen. In der dritten Phase werde ich an der Struktur, dem Erscheinungsbild und der Benutzerfreundlichkeit von Vorlagen aus ReadTheDocs- und Google Docs-Dokumenten arbeiten. Ich werde eine Vorlagen- und ein Image-Repository in Google Drive erstellen und jede Vorlagenkategorie der Hauptdokumenttypen identifizieren, die in zukünftigen Implementierungen wiederverwendet werden kann. Ich werde diese Aufgabe ergänzen, indem ich Vorlagen zum Einreichen von Dokumentenproblemen erstelle, damit sie bei der Überprüfung von Pull-Requests leichter identifiziert werden können. Schließlich erstelle ich einen Leitfaden für Mitwirkende, in dem nützliche Ressourcen für jede Gruppe von Mitwirkenden zusammengestellt werden, um den Zugriff auf Informationen zu erleichtern.

Zweck und Umfang

Mit diesem Implementierungsplan soll die Nutzung der Kolibri-Dokumente für Endnutzer verbessert und Teammitgliedern und Mitwirkenden eine bessere Dokumentation und aktive Zusammenarbeit in der Community ermöglicht werden. Diese Implementierung gilt für ReadTheDocs und Teilmengen von Google Docs-Dokumenten im Kolibri-System.

Zielgruppe

Die primäre Zielgruppe sind Implementierer, Administratoren und Endnutzer, die die wichtigsten Nutzer der Kolibri-Dokumentation sind. Eine sekundäre Zielgruppe von Teammitgliedern und Mitwirkenden für die Erstellung und Nutzung der Kolibri-Dokumentation.

Zielsetzungen

Gemäß dem Styleguide und dem Workflowsystem für die Kolibri-Ekosystemdokumentation müssen Nutzer: Verständliche Dokumentation mit barrierefreier Sprache und einheitlichem Layout erstellen. Achten Sie bei der Dokumentation auf die Einhaltung von Qualitätspraktiken. Sorgen Sie zwischen verschiedenen Dokumentationskanälen für einen einfachen Zugriff auf Informationen. Die kollaborativen Initiativen in der Open-Source-Community von Kolibri stärken.

Informationsquellen

Meine Informationsquellen waren Kolibri, Kolibri Studio, Kolibri Development RTD-Dokumente und Kolibri-Toolkits von Google Drive.
Die wunderbare Radina Matic war eine große Hilfe bei der Bereitstellung von Aufwärm- und projektspezifischen Aktivitäten. Ihre Informationen dazu, was die Organisation als „Richtlinien“ und „Leitfäden“ versteht und ob es einen Leitfaden für Mitwirkende gibt, haben mir geholfen, meine Ideen zu strukturieren und Schlussfolgerungen zu formulieren.

Software

Ich werde den Entwurf des Styleguides in Google Docs entwickeln. Diese Dokumentenplattform eignet sich perfekt für Iterationen, während das Dokument für die Veröffentlichung bereit ist. Für die QA-Analyse verwende ich Google Formulare, um Dokumente zu erstellen und zu bewerten. In einer Tabelle werden Formularantworten für die Dokumentenkontrolle gespeichert. Ich werde RTD-Dokumente mit GitHub umstrukturieren. Ich habe mit Git, Gitkraken, GitHub und Gitlab gearbeitet. Ich habe Arbeitskenntnisse zu Markdown und ein paar RestructuredText. Ich möchte an der Fehlerbehebung in der Dokumentation mitarbeiten, um die Syntax weiter zu lernen. Ich verwende ShareX für Bilder und GIFs. Ich mag dieses Tool, weil es in verschiedenen Ausgabeformaten rendert. Ich verwende „Diagramme“ für die Erstellung von Diagrammen und die Bildausgabe. Die Diagrammsoftware lässt sich nahtlos in Google Docs, Google Drive und LibreOffice einbinden. Stand der Dokumentation In der explorativen Phase habe ich den Großteil der Kolibri-Dokumentation überarbeitet. Ich habe grammatikalische Fehler, Tippfehler, Inkonsistenzen in Layout, Typografie, Bildnutzung und verwirrende Dokumentationspfade in der gesamten Projektdokumentation gefunden. Im Nutzerhandbuch von Kolibri ist der Abschnitt zur Fehlerbehebung beispielsweise ein Unterthema und kein Thema. Diese Informationen sind so wichtig, dass Endnutzer über den Inhaltsverzeichniszugriff darauf zugreifen können. Alternativ können sie die Suchleiste und den Inhaltsverzeichnisbaum verwenden, um andere Themen zu erweitern und Artikel zur Fehlerbehebung zu finden.

Wenn Sie den Abschnitt „Fehlerbehebung“ aufrufen möchten, müssen Sie entweder danach suchen oder „Kolibri verwalten“ maximieren, um zu sehen, dass die Fehlerbehebung Teil der Dokumentation ist. Leitfaden vs. Richtlinien Für diesen Projektvorschlag habe ich zwei Dokumente analysiert: LE Kolibri User Documentation Style Guide und LE Translation Guidelines. Im LE Kolibri-Leitfaden habe ich Empfehlungen und Kommentare aus meinem vorgeschlagenen Themenplan und Dokumentationsplan sowie einige andere Dinge gemacht, die im Leitfaden verbessert werden müssen. Für die LE Translation Guidelines habe ich das Format und den Stil basierend auf meinen Empfehlungen und den bestehenden Konventionen im Styleguide geändert. Bei der Analyse fiel mir vor allem die Fehlinterpretation auf, die zwischen Dokumenten besteht, die als Leitfaden und Richtlinien kategorisiert sind.

Ergebnisse

Ich habe den Leitfaden für die Übersetzung von Lernmaterialien zusätzlich zu Vorschlägen und Kommentaren mit einem vorläufigen Formular geprüft, das ich in der Aufgabe zur QA-Prüfung genauer erläutere. Hier sind einige abschließende Kommentare aus der Bewertung: Fehlerhafte Links auf der ICU-Syntax-.js-Website Das zum Erstellen dieser Richtlinien verwendete Format ist falsch. Das Dokument ist ein Leitfaden, keine Richtlinien. Uneinheitliche Typografie Falsche Verwendung von Überschriften und Titeln, unsachgemäßer Gebrauch von Sprache und Missbrauch von Kontraktionen. Unzulässige Verwendung von alternativen Texten Wiederholte Aussagen/ Anweisungen

Die Ergebnisse beider Dokumente sind Teil der Liefergegenstände für dieses Angebot.

Projektspezifische Aufgaben

• Empfehlungen für den Styleguide für die Nutzerdokumentation (Kommentare)
• LE Translation Guidelines mit neuen Stilen und Format.
• Themenübersicht
• Projektzeitplan
• Dokumentationsaufgaben