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

Kolibri

Technischer Redakteur:

StephDix

Projektname:

Konventionen für Stil und Workflows in der Dokumentation zum Kolibri-Ökosystem

Projektdauer:

Langfristig (5 Monate)

Projektbeschreibung

Zusammenfassung

In diesem Dokument wird die Implementierung der Stilrichtlinien und des Workflow-Managements in die dokumentierten Informationen von Learning Equality für das Kolibri-Ökosystem beschrieben.

Überblick

Mein Vorschlag besteht aus vier Phasen. In der ersten Phase werde ich den LE Documentation Style Guide mit Richtlinien zur Barrierefreiheit, Schreib- und Formatempfehlungen gemäß LE-Konzepten und Stilrichtlinien in der Softwareentwicklung fertigstellen. In der zweiten Phase werde ich eine Qualitätsprüfung für die Dokumente ReadTheDocs und GoogleDocs durchführen. Der Prüfplan integriert die Verwendung von Checklisten, um die Einhaltung der Stilrichtlinien zu bewerten. Diese Checklisten helfen Ihnen, Ergebnisse aufzuzeichnen und Änderungen an der Dokumentation anzuwenden. In der dritten Phase arbeite ich an der Struktur, dem Erscheinungsbild und der Handhabung von Vorlagen aus ReadTheDocs- und GoogleDocs-Dokumenten. Ich werde in Google Drive ein Repository mit Vorlagen und Bildern erstellen und darin die einzelnen Vorlagenkategorien der Hauptdokumenttypen angeben, die bei künftigen Implementierungen wiederverwendet werden können. Ich werde diese Aufgabe ergänzen und Vorlagen erstellen, um Dokumentprobleme einzureichen, damit sie bei der Überprüfung von Pull-Anfragen leicht identifiziert werden können. Abschließend werde ich einen Contributors Guide erstellen, in dem nützliche Ressourcen für jede Gruppe von Mitbearbeitern aufgeführt sind, damit diese noch besser auf Informationen zugreifen können.

Zweck und Umfang

Ziel dieses Implementierungsplans ist es, die Nutzerfreundlichkeit der Dokumente von Kolibri zu verbessern und Teammitgliedern und Mitwirkenden dabei zu helfen, eine bessere Dokumentation und eine aktive Zusammenarbeit in der Community zu entwickeln. Diese Implementierung gilt für ReadTheDocs und Untergruppen von Google Docs-Dokumenten im Kolibri-Ökosystem.

Zielgruppe

Eine Hauptzielgruppe von Implementierern, Administratoren und Endnutzern, die die kritischste Konsumenten der Kolibri-Dokumentation darstellen. Eine sekundäre Zielgruppe von Teammitgliedern und Mitbearbeitern für die Produktion und Verwendung der Kolibri-Dokumentation.

Zielsetzungen

Die Dokumentation für den Styleguide und das Workflow-System für die Dokumentation des Kolibri-Ökosystems erfordert Folgendes: Eine leicht verständliche Dokumentation mit barrierefreier Sprache und einheitlichem Layout. Aufrechterhaltung der Aufrechterhaltung der Qualitätsverfahren bei der Dokumentation. Einfacher Zugriff auf Informationen zwischen Dokumentationskanälen Stärkung der Kooperationsinitiativen in der Open-Source-Community Kolibri

Informationsquellen

Meine Informationsquellen waren Kolibri, Kolibri Studio, RTD-Dokumente von Kolibri Development und Kolibri Toolkits von Google Drive.
Das wundervolle Radina Matic war eine große Hilfe bei Aufwärmübungen und projektspezifischen Aktivitäten. Ihre Angaben zu den Konzepten der Organisation als „Richtlinien“ und „Leitfäden“ und zur Existenz eines Handbuchs für Mitwirkende halfen mir, meine Ideen zu strukturieren und Schlussfolgerungen zu verfassen.

Software

Ich werde den Entwurf des Styleguides in Google Docs entwickeln. Diese Dokumentenplattform ist perfekt für die Iteration, wenn sie bereit für die Veröffentlichung ist. Für das QA-Audit werde ich Google Formulare verwenden, um Dokumente zu erstellen und zu bewerten. In einer Tabelle werden Formularantworten zur Dokumentsteuerung gespeichert. Ich werde RTD-Dokumente mithilfe von GitHub refaktorieren. Ich habe mit Git, Gitkraken, GitHub und Gitlab gearbeitet. Ich habe Erfahrung mit Markdown und ein paar RestructuredText. Ich werde an Dokumentationskorrekturen mitwirken, um die Syntax weiter zu lernen. Ich werde Sharex für Bilder und GIFs verwenden. Ich liebe dieses Tool, weil es in verschiedenen Ausgabeformaten rendert. Ich nutze „Diagramme“ für Diagramme und die Bildausgabe. Diagrammsoftware lässt sich problemlos in Google Docs, Google Drive und LibreOffice einbinden. Stand der Dokumentation In der Erkundungsphase habe ich die meisten der Dokumentation von Kolibri überarbeitet. Ich habe grammatische Fehler, Tippfehler, Inkonsistenzen beim Layout, der Typografie und der Bildnutzung sowie verwirrende Dokumentationspfade gefunden. Im Kolibri-Nutzerhandbuch ist der Abschnitt zur Fehlerbehebung beispielsweise ein untergeordnetes Thema und kein Thema. Diese Informationen sind so wichtig, dass Endnutzer über das Inhaltsverzeichnis darauf zugreifen können. Als zweite Alternative können sie die Suchleiste und das Inhaltsverzeichnis verwenden, um andere Themen zu erweitern und Artikel zur Fehlerbehebung zu finden.

Um auf den Abschnitt „Fehlerbehebung“ zuzugreifen, müssen Sie entweder danach suchen oder „Kolibri verwalten“ maximieren. Sie sehen dann, dass die Fehlerbehebung Teil der Dokumentation ist. Leitfaden und Richtlinien Für diesen Projektvorschlag habe ich zwei Dokumente analysiert: LE Kolibri User Documentation Style Guide und LE Translation Guidelines. Im LE Kolibri Guide habe ich Empfehlungen und Kommentare zu meiner Themenübersicht und dem Dokumentationsplan sowie andere Dinge gemacht, die verbessert werden sollten. Für die LE Translation Guidelines habe ich das Format und den Stil basierend auf meinen Empfehlungen und den bestehenden Konventionen im Style Guide geändert. Mir ist während der Analyse am meisten auf die Missverständnisse zwischen den Dokumenten der Kategorie „Leitfaden und Richtlinien“ aufmerksam geworden.

Ergebnisse

Ich habe eine Qualitätsprüfung für den LE Translation Guide zusätzlich zu den Vorschlägen und Kommentaren mit einem vorläufigen Formular durchgeführt, das ich in der Aufgabe des QA-Audits ausführlicher erläutere. Hier sind einige abschließende Kommentare aus der Bewertung: Fehlerhafte Links für die ICU Syntax .js-Website Das zur Erstellung dieser Richtlinien verwendete Format ist falsch. Das Dokument ist eine Anleitung, keine Richtlinien. Uneinheitliche Typografie. Falsche Verwendung von Überschriften und Titeln, Falsche Verwendung von Ausdrücken und Falsche Verwendung von Kontraktionen. Unangemessene Verwendung alternativer Texte. Über wiederholte Anweisungen/ Anweisungen.

Die Ergebnisse aus beiden Dokumenten sind Teil der Liefergegenstände für dieses Angebot.

Projektspezifische Aufgaben

• LE Style Guide-Empfehlungen für Nutzerdokumentationen (Kommentare)
• LE Translation-Richtlinien mit neuen Stilen und neuen Formaten.
• Themenübersicht
• Projektzeitplan
• Dokumentationsaufgaben