Co-Pilotprojekt für Performance Marketing

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:
Leistungs-Copilot
Technischer Redakteur:
arzoo14
Projektname:
Inhalte von Buchprojektbereichen in das readthedocs- und reStructuredText-Format konvertieren, sowie das Stretch-Ziel der Verbesserung von Diagrammen.
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

ABSTRACT:

Eine Community-Website spielt in einer Open-Source-Organisation eine wichtige Rolle, da sie die Idee der Angebote der Community, ihre wertvollen Beiträge, ihre Fähigkeiten, ihre Dokumentationen, ihre Anleitungen usw. verbreitet. Daher zielt mein Projekt darauf ab, die Nutzerfreundlichkeit und Einfachheit für alle Open-Source-Mitwirkenden zu verbessern, indem die Inhalte der Buchprojektbereiche, d. h. DocBook-Inhalte, REST API-Dokumentation und Pbench-Markdown-Inhalte, in das reStructuredText-Format übertragen und aktualisiert werden, damit sie auf der modernen Community-Website readthedocs.io gehostet werden können. Dieses Projekt kommt auch den Mitwirkenden der Community zugute, da diese die Möglichkeit haben, diese Inhalte leichter zu ändern und zu erweitern. Als Stretch-Ziel werden auch die Diagramme in der Dokumentation verbessert, um ihnen ein professionelleres Aussehen zu verleihen.

VORSCHLAG:

  1. ÜBERBLICK: Die Dokumentation zu Performance Co-Pilot ist derzeit in mehreren verschiedenen Formaten verfügbar. Dazu gehören PCP-Bücher im DocBook-Format, REST API im Manpage-Format und pbench-Anleitungen im Markdown-Format. Die aktuelle Wartungsgruppe der Organisation stellte daher fest, dass sie eine Lösung benötigt, die so wartungsfrei wie möglich ist und die es der Entwicklergemeinschaft ermöglicht, sich ganz darauf zu konzentrieren, ihre Inhalte auf einfache und effiziente Weise zu verwalten. Daher werde ich während der Google Season of Docs die folgenden Ziele entsprechend den aktuellen Anforderungen der Organisation umsetzen:

    1. Docbook-Inhalte in das reStructuredText-Format konvertieren und auf der readthedocs-Website hosten.
    2. REST API-Dokumentation aus der Manpage in ein für Entwickler geeignetes Format konvertieren, z.B. in das reStructuredText-Format, und auf der readthedocs-Website hosten.
    3. pbench MarkDown-Inhalte werden in das reStructuredText-Format konvertiert und auf der readthedocs-Website gehostet.
    4. Als Stretch-Goals könnten Sie sich vornehmen, die in der Dokumentation enthaltenen Diagramme zu verbessern.

  2. IMPLEMENTIERUNG: Die Dokumentation zum Co-Pilot-Projekt zur Leistungsüberwachung steht derzeit nicht in einem bestimmten Format zur Verfügung. Wenn der Inhalt der Dokumentation geändert werden muss, muss dies von einer begrenzten Anzahl von Nutzern erfolgen. Es ist für die aktiven Communitymitglieder nicht ganz einfach, den Inhalt der Dokumentation zu ändern und zu erweitern.

Ich werde der Organisation helfen, diese Einschränkungen während dieses GSoD mithilfe des reStructuredText-Formats, Read the Docs (RTD) und Sphinx zu überwinden.

Read the Docs (RTD) vereinfacht die Softwaredokumentation, indem das Erstellen, Versionieren und Hosten unserer Dokumente automatisiert wird. Es ist eine Hostingplattform für Sphinx-generierte Dokumentationen. Es nutzt die Leistung von Sphinx und bietet Versionskontrolle, Volltextsuche und andere nützliche Funktionen. Es ruft Code- und Dokumentdateien aus Git, Mercurial oder Subversion ab und erstellt und hostet dann unsere Dokumentation. Wir verwenden in unserem Projekt GitHub, da es das am häufigsten verwendete System für den Zugriff auf Code ist.

Zuerst erstellen wir ein Read the Docs-Konto und verknüpfen es mit dem GitHub-Konto. Dann wählen wir das GitHub-Repository aus, für das wir eine Dokumentation erstellen möchten.

Read the Docs führt folgende Schritte aus: - Unser Repository wird geklont. – HTML-, PDF- und EPUB-Versionen unserer Dokumentation aus unserem Master-Branch erstellen. – Unsere Dokumentation wird indexiert, um eine Volltextsuche zu ermöglichen. – Versionenobjekte aus jedem Tag und jedem Branch in unserem Repository erstellen, sodass wir diese optional auch hosten können. – Wir aktivieren einen Webhook in unserem Repository, damit unsere Dokumentation jedes Mal neu erstellt wird, wenn wir Code in einen beliebigen Branch pushen.

Sphinx ist ein vertrauenswürdiger Dokumentationsgenerator mit vielen nützlichen Funktionen für die Erstellung technischer Dokumentationen. Dazu gehören: - Webseiten, druckbare PDFs, Dokumente für E-Reader (ePub) und mehr aus denselben Quellen generieren. – Wir können reStructuredText zum Erstellen von Dokumentationen verwenden. – Ein umfangreiches System von Querverweisen zwischen Code und Dokumentation. – Syntax hervorgehobene Codebeispiele. – Ein lebendiges Ökosystem aus Erweiterungen von Erst- und Drittanbietern.

Ich beginne damit, die beiden PCP-Bücher, die im DocBook-Format vorliegen, in das rst-Format zu konvertieren. Anschließend konvertiere ich die REST API-Dokumentation aus dem Manpage-Format in das rst-Format, dann die Markdown-Inhalte von pbench in das rst-Format und hoste sie schließlich alle auf der readthedocs-Website. Die Stretch-Ziele wären die Verbesserung der Diagramme in der Dokumentation.

2.1. Konvertierung in das ReStructuredText-Format: Der erste Schritt besteht darin, den Dokumentationsinhalt in das ReStructuredText-Format umzuwandeln. Jedes Kapitel hat eine separate rst-Datei, die nur den Inhalt dieses Kapitels enthält. Beispielsweise besteht das Buch „Performance Co-Pilot User's and Administrator's Guide“ aus acht Kapiteln. Das bedeutet, dass es acht verschiedene rst-Dateien gibt, die diesen acht Kapiteln entsprechen. Der Name der rst-Datei muss mit dem Kapitelnamen übereinstimmen, um Verwechslungen zu vermeiden. Eine Liste der Abbildungen, Tabellen und Beispiellisten befindet sich in drei verschiedenen rst-Dateien. Der RST-Inhalt wird genau wie derzeit vorhanden mit Hyperlinks versehen. Das gilt auch für die REST API-Dokumentation und die pbench-Inhalte. Alle erforderlichen Elemente wie Fettdruck, Kursivschrift, Unterstreichungen, Aufzählungspunkte, Tabellen, Schriftgröße, Codestil, Bildgröße, Ausrichtung usw. werden bei der Umwandlung in das rst-Format berücksichtigt.

2.2. Integration von rst in Sphinx:

ReadtheDocs verwendet standardmäßig Sphinx und reStructuredText (rst). Da Sphinx auf meinem System vorinstalliert ist, erstelle ich zuerst ein Verzeichnis innerhalb des Projekts (namens Performance Co-Pilot Documentation), um die Dokumente zu speichern: $ cd /path/to/project $ mkdir docs

Führen Sie dann dort sphinx-quickstart aus: $ cd docs $ sphinx-quickstart

In dieser Kurzanleitung wird beschrieben, wie Sie die erforderliche Konfiguration erstellen. In den meisten Fällen können Sie einfach die Standardeinstellungen akzeptieren. Bei Bedarf können Sie aber die erforderlichen Änderungen in der Konfigurationsdatei vornehmen. Wenn der Vorgang abgeschlossen ist, haben wir die Dateien „index.rst“, „conf.py“ und einige andere Dateien. In index.rst füge ich alle erforderlichen Details zum Performance Co-Pilot hinzu und erstelle Überschriften für die Bücher, die REST API-Dokumentation und die pbench-Anleitungen. Wenn der Nutzer auf eine der Überschriften klickt, werden alle zugehörigen Dokumentationsmaterialien geöffnet.

HINWEIS: Das Design der Indexseite richtet sich nach der Zustimmung der beratenden Personen und Communitymitglieder und wird entsprechend den Anforderungen und Anforderungen angepasst.

Die Datei „index.rst“ wird in die Datei „index.html“ im Ausgabeverzeichnis der Dokumentation eingefügt (in der Regel _build/html/index.html). Sobald wir die Sphinx-Dokumentation in einem öffentlichen Repository haben, können wir Read the Docs verwenden, indem wir unsere Dokumente importieren.

Wenn wir unserer Dokumentation eine .rst-Datei hinzufügen, werden drei weitere Dateien generiert, eine im Ordner „doctrees“ mit der Erweiterung „.doctree“, eine im Ordner „html“ mit der Erweiterung „.html“ und die dritte im Ordner „html/_sources“ mit der Erweiterung „.rst.txt“.

  1. HOSTING DER DOKUMENTATION: Das Hosting der Dokumentation im Internet umfasst zwei Schritte: 1. Dokumentation importieren: Als ersten Schritt verknüpfe ich das Read The Docs-Konto mit GitHub und importiere unser Dokumentationsprojekt zum Erstellen. 2. Erstellen der Dokumentation: Wenige Sekunden nach Abschluss des Importvorgangs wird der Code automatisch aus unserem öffentlichen Repository abgerufen und die Dokumentation wird erstellt.

  2. WEBHOOKS: Die primäre Methode, mit der Read the Docs Änderungen an der Dokumentation und den Versionen erkennt, ist die Verwendung von Webhooks. Webhooks werden bei unserem Repository-Anbieter wie GitHub konfiguriert. Bei jedem Commit, Merge oder einer anderen Änderung an unserem Repository wird Read the Docs benachrichtigt. Wenn wir eine Webhook-Benachrichtigung erhalten, prüfen wir, ob sich die Änderung auf eine aktive Version unseres Projekts bezieht. Ist das der Fall, wird für diese Version ein Build ausgelöst.

Auf diese Weise kann jeder (Administratoren, Mentoren, Community-Mitwirkende) die Community-Dokumentation ändern, erweitern oder pflegen. Es ist keine spezielle eingeschränkte Gruppe von Nutzern erforderlich, um sich darum zu kümmern, was in die Dokumentation aufgenommen oder aus der Dokumentation entfernt werden sollte.

  1. THEMEN: Themen, Layouts, Designs und andere HTML-Funktionen wie die Suche richten sich nach den Anforderungen und Richtlinien der Community. In der Phase des Community-Bondings werde ich diese Themen mit den Community-Mitgliedern besprechen.
  1. STRETCH-ZIEL: Wir werden die Diagramme in der Dokumentation verbessern. Derzeit sind die Diagramme größtenteils einfache Schwarz-Weiß-Zeichnungen. Ich werde mehr Farbe, Schattierung, Skalierung, Einheitlichkeit und ein insgesamt ordentlicheres / professionelleres Aussehen der Bilder einführen.

Dazu verwende ich draw.io (oder ein anderes Tool mit der Zustimmung des Mentors).

Als Proof of Concept habe ich eines der Diagramme in der Dokumentation mithilfe von draw.io verbessert. Hier ist er: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

PROOF OF CONCEPT

Ich habe einen kleinen Teil des PCP-Buchs (DocBook-Format) in das rst-Format konvertiert und auf der readthedocs-Website gehostet. Sie finden sie hier.

Website: https://pcp-books.readthedocs.io/de/latest/ Code: https://github.com/arzoo14/PCP_Books_Demo

Ich habe auch Webhooks im Code-Repository konfiguriert. Damit werden die im Code-Repository vorgenommenen Änderungen auf der Website widergespiegelt.

ZEITPLAN UND LEISTUNGEN

COMMUNITY BONDING PERIOD [ August 17 - September 13, 2020 ]

Ich werde diese Zeit damit verbringen, mich mit der Community vertraut zu machen, die Dokumentation durchzugehen und viele Dinge mit den Mentoren zu besprechen, damit keine schlechten Entscheidungen zu Beginn des Prozesses getroffen werden. In dieser Zeit werde ich mit den Mentoren und den Community-Mitgliedern über Themen, Layouts, Designs und andere Funktionen wie Suche, Navigationsleiste usw. sprechen. Die Entscheidung für den Namen des Projekts und ob es eine einzige Website für alle drei Themen oder drei verschiedene Websites für die drei Themen geben wird, wird während der Phase des Community-Bondings besprochen.

ZEITRAUM DER DOKUMENTENTWICKLUNG [14. September bis 30. November 2020 ]

***14. bis 20. September 2020 [WOCHE 1] Umwandlung von DocBook-Inhalten in das rst-Format für die ersten vier Kapitel des Handbuchs für Nutzer und Administratoren.

***Vom 21. September 2020 bis 27. September 2020 [WOCHE 2] Konvertierung des Dokumentinhalts in das erste Format für die nächsten vier Kapitel des Leitfadens für Nutzer und Administratoren.

***28. September 2020 bis 4. Oktober 2020 [WOCHE 3] Umwandlung der DocBook-Inhalte in das rst-Format für alle vier Kapitel des Programmierhandbuchs.

***Vom 5. Oktober 2020 bis 11. Oktober 2020 [WOCHE 4] – Hosting beider PCP-Bücher auf der readthedocs-Website. – Umstellung der REST API-Dokumentation von der Manpage in das rst-Format Die Haupt-Landingpage wird während dieses Zeitraums ausgeblendet. – Bloggen (über mein GSoD-Projekt) in den letzten drei Wochen und in der aktuellen Woche.

***12. bis 18. Oktober 2020 [WOCHE 5] Umstellung des skalierbaren Zeitreihenindexes in das rst-Format. Der skalierbare Zeitreihenindex umfasst Folgendes: GET /series/query , GET /series/values, GET /series/descs , GET /series/labels, GET /series/metrics , GET /series/sources , GET /series/instances , GET /series/load

***19. bis 25. Oktober 2020 [WOCHE 6] Umstellung des PMAPI-Hostdienst-Indexes in das rst-Format. Der PMAPI-Hostdienstindex umfasst Folgendes: GET /pmapi/context, GET /pmapi/metric, GET /pmapi/fetch , GET /pmapi/children GET /pmapi/indom, GET /pmapi/profile , GET /pmapi/store , GET /pmapi/derive GET /pmapi/metrics

***26. Oktober 2020 bis 1. November 2020 [WOCHE 7]: – Falls noch etwas aus den letzten Wochen offen ist, wird es zuerst behandelt. – Hosting der REST API-Dokumentation auf der readthedocs-Website. - Blogging (für mein GSoD-Projekt) in den letzten zwei Wochen und in der aktuellen Woche

***2. bis 8. November 2020 [WOCHE 8] Umwandlung der Markdown-Inhalte in das rst-Format für die Pbench-Anleitungen.

***Vom 9. November 2020 bis 15. November 2020 [WOCHE 9] – Die Markdown-Inhalte werden in den Pbench-Leitfäden in das erste Format konvertiert. – Hosting der pbench-Anleitungen auf der readthedocs-Website. – Bloggen (über mein GSoD-Projekt) in der letzten und der aktuellen Woche.

***16. bis 22. November 2020 [WOCHE 10] – Implementierung der Suchfunktion auf der Indexseite, um nach Inhalten anhand ihres Namens auf den Websites zu suchen. – Vormals an Dehnübungen.

***23. bis 30. November 2020 [WOCHE 11] Verbesserung aller Diagramme in der Dokumentation. – Der letzte Blogbeitrag für mein GSoD-Projekt in der letzten und der aktuellen Woche – Prüfen, ob die Codebasis den Codierungsstandards entspricht. Wenn nicht, ändern Sie sie auf die Standards.

PROJEKTABSCHLUSSZEITRAUM [30. November bis 5. Dezember 2020 ]

  • Ausfallzeit des Bleistifts Ich arbeite an der endgültigen Einreichung und prüfe, ob alles in Ordnung ist.
  • Einreichen der Projektberichte, auch als Endprodukte bezeichnet.
  • Einreichung der Bewertungen zum Erfolg der Projekte und der Berufserfahrung mit den beratenden Personen.