Co-Pilotprojekt für Performance Marketing

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:
Performance-Co-Pilot
Technischer Redakteur:
arzoo14
Projektname:
Konvertieren Sie den Inhalt von Buchprojektbereichen in das Format „readthedocs“ und „reStructuredText“ und verfolgen Sie dabei das eigentliche Ziel der Verbesserung von Diagrammen.
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

ZUSAMMENFASSUNG:

Eine Community-Website spielt in einer Open-Source-Organisation eine wichtige Rolle, da sie die von der Community bereitgestellten Angebote, ihre wertvollen Beiträge, ihre Fähigkeiten, ihre Dokumentationen und Anleitungen usw. verbreitet.Mein Projekt zielt daher darauf ab, die Nutzerfreundlichkeit und Einfachheit für alle Open-Source-Mitwirkenden zu verbessern, indem die Inhalte des Buchprojektbereichs übertragen und aktualisiert werden, d. h.DOCbook-Inhalte, REST API-Dokumentation und das. Von diesem Projekt profitieren auch die Beiträge der Community, da sie die Inhalte leichter ändern und erweitern können. Das Ziel ist es, die Diagramme in der Dokumentation noch professioneller zu gestalten.

VORSCHLAG:

  1. ÜBERSICHT: Die Dokumentation zum Performance Co-Pilot-Projekt ist derzeit in verschiedenen Formaten verfügbar. Dazu gehören PCP-Bücher im DOCbook-Format, die REST API im Manpage-Format und PBench-Leitfäden im Markdown-Format. Die aktuelle Gruppe der IT-Administratoren der Organisation stellte daher fest, dass sie eine Lösung benötigen, die so wartungsfrei wie möglich ist und die es der Entwickler-Community ermöglicht, sich ganz auf die Pflege der Inhalte auf optimierte und einfache Weise zu konzentrieren. In Anbetracht der aktuellen Anforderungen der Organisation werde ich während der Google Docs-Saison von Google Docs die folgenden Ziele umsetzen:

    1. DOCbook-Inhalte werden in das reStructuredText-Format konvertiert und auf der Website readthedocs gehostet.
    2. Konvertierung der REST API-Dokumentation von der Manpage in ein entwicklerfreundliches Format, d.h. das Format „reStructuredText“ und das Hosten der Dokumentation auf der Website readthedocs.
    3. PBench MarkDown-Inhalte werden in das reStructuredText-Format konvertiert und auf der Website readthedocs gehostet.
    4. Stretch-Ziele wären die Verbesserung der in der Dokumentation vorhandenen Diagramme.

  2. IMPLEMENTIERUNG: Derzeit liegt die Dokumentation zum Performance-Co-Pilot-Projekt nicht in einem bestimmten Format vor. Wenn der Inhalt der Dokumentation geändert werden muss, muss er von einer eingeschränkten Gruppe von Nutzern geändert werden. Für die aktiven Community-Mitglieder ist es nicht so einfach, den Inhalt der Dokumentation zu ändern und zu erweitern.

Ich werde die Organisation während dieser GSoD mithilfe des reStructuredText-Formats, Read the Docs (RTD) und Sphinx überwinden lassen.

Die Dokumentation lesen (RTD) vereinfacht die Softwaredokumentation, indem das Erstellen, die Versionsverwaltung und das Hosting unserer Dokumente für uns automatisiert werden. Es ist eine Hosting-Plattform für Sphinx-generierte Dokumentation. Es nutzt die Leistungsfähigkeit von Sphinx und bietet Versionskontrolle, Volltextsuche und weitere nützliche Funktionen. Es ruft Code- und DOC-Dateien aus Git, Mercurial oder Subversion ab und erstellt und hostet unsere Dokumentation. Wir verwenden GitHub in unserem Projekt, da dies das am häufigsten verwendete System für den Zugriff auf Code ist.

Zuerst erstellen wir ein „Read the Docs“-Konto und verknüpfen das GitHub-Konto. Dann wählen wir das GitHub-Repository aus, für das wir die Dokumentation erstellen möchten. Dann geschieht dies.

Lesen Sie die Dokumente: - Klonen Sie unser Repository. – HTML-, PDF- und EPUB-Versionen unserer Dokumentation in unserem Hauptzweig erstellen. – Indexierung unserer Dokumentation, um eine Volltextsuche zu ermöglichen – Versionsobjekte aus jedem Tag und Zweig in unserem Repository erstellen, sodass wir diese optional auch hosten können. – Aktivieren Sie einen Webhook in unserem Repository, sodass unsere Dokumentation neu erstellt wird, wenn wir Code in einen Zweig übertragen.

Sphinx ist ein zuverlässiger Dokumentationsgenerator, der viele großartige Funktionen zum Schreiben technischer Dokumentation bietet, darunter: – Sie können aus denselben Quellen Webseiten, druckbare PDFs und Dokumente für E-Reader (EPUB) erstellen. – Wir können reStructuredText verwenden, um eine Dokumentation zu schreiben. – Ein umfassendes System mit Querverweisen auf Code und Dokumentation – Syntax hervorgehobene Codebeispiele – Vielfältige Auswahl an Erweiterungen von Erst- und Drittanbietern.

Ich beginne damit, die beiden PCP-Bücher, die im Docbook-Format vorliegen, in das erste Format zu konvertieren, nachdem ich die REST API-Dokumentation vom Man-Page-Format in das erste Format konvertiert und dann den PBench Markdown-Inhalt in das erste Format konvertiert und am Ende alle diese auf der readthedocs-Website gehostet. Das eigentliche Ziel wäre, die Diagramme in der Dokumentation zu verbessern.

2.1. Konvertierung in das Format „reStructuredText“: Der erste Schritt besteht darin, die Dokumentation in das Format „reStructuredText“ zu konvertieren. Für jedes Kapitel gibt es eine eigene erste Datei, die nur den Inhalt des jeweiligen Kapitels enthält. Das Buch „Performance Co-Pilot User's and Administrator's Guide“ enthält beispielsweise acht Kapitel. Das bedeutet, dass es acht verschiedene erste Dateien für diese acht Kapitel gibt. Der Name der ersten Datei ist identisch mit dem Kapitelnamen, um zukünftige Verwechslungen zu vermeiden. Eine Liste mit Abbildungen, Tabellen und Beispiellisten befindet sich in drei verschiedenen ersten Dateien. Die ersten Inhalte werden genau wie bisher mit einem Hyperlink versehen. Für die REST API-Dokumentation und PBench-Inhalte wird dasselbe verwendet. Alle erforderlichen Elemente wie Fett- und Kursivformatierung, Unterstrich, Aufzählungspunkte, Tabellen, Schriftgröße, Codestil, Bildgröße, Ausrichtung usw. werden beim Konvertieren der Inhalte in das erste Format übernommen.

2.2. Integration von Erst in Sphinx:

ReadtheDocs verwendet Sphinx und reStructuredText (erste) als Standardeinstellungen. Da Sphinx in meinem System vorinstalliert ist, beginne ich mit dem Erstellen eines Verzeichnisses im Projekt (mit dem Namen „Performance Co-Pilot Documentation“) für die Dokumente: $ cd /path/to/project $ mkdir Dokumente

Führen Sie anschließend dort sphinx-quickstart aus: $ cd docs $ sphinx-quickstart

In diesem Schnellstart wird Schritt für Schritt erklärt, wie Sie die erforderliche Konfiguration erstellen. In den meisten Fällen können wir einfach die Standardeinstellungen übernehmen. Bei Bedarf können wir jedoch die wesentlichen Änderungen an der Konfigurationsdatei vornehmen. Wenn der Vorgang abgeschlossen ist, haben wir eine index.rst, eine 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-Leitfäden. Wenn Nutzende auf eine der Überschriften klicken, werden alle Dokumentationsmaterialien unter dieser Überschrift geöffnet.

HINWEIS: Das Design der Indexseite richtet sich nach der Zustimmung der Mentoren und Community-Mitglieder und wird an die Anforderungen und Anforderungen angepasst.

Die Datei "index.rst" wird in unser Ausgabeverzeichnis der Dokumentation (normalerweise "_build/html/index.html") in die Datei "index.html" integriert. Sobald wir die Sphinx-Dokumentation in einem öffentlichen Repository haben, können wir mit der Verwendung von Read the Docs beginnen, indem wir unsere Dokumente importieren.

Wenn wir eine .rst-Datei in unsere Dokumentation einfügen, werden entsprechend dieser Datei drei weitere Dateien erstellt: eine im Ordner „.doctrees“ mit der Erweiterung „.doctree“, die zweite 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: Zuerst verbinde ich das „Lesen Sie die Dokumente“-Konto mit GitHub und importiere unser Dokumentationsprojekt, um es zu erstellen. 2. Erstellen der Dokumentation: Innerhalb weniger Sekunden nach Abschluss des Importvorgangs wird der Code automatisch aus unserem öffentlichen Repository abgerufen und die Dokumentation wird erstellt.

  2. WEBHOOKS: Die Hauptmethode zur Erkennung von Änderungen an der Dokumentation und den Versionen bei Read the Docs sind Webhooks. Webhooks werden mit unserem Repository-Anbieter wie GitHub konfiguriert. Bei jedem Commit, Zusammenführung oder jeder anderen Änderung an unserem Repository wird Read the Docs benachrichtigt. Wenn wir eine Webhook-Benachrichtigung erhalten, ermitteln wir, ob die Änderung mit einer aktiven Version für unser Projekt zusammenhängt. Ist dies der Fall, wird ein Build für diese Version ausgelöst.

Auf diese Weise kann jeder (Administratoren, Mentoren, Community-Mitwirkende) die Community-Dokumentation ändern, erweitern oder pflegen, und es wird keine bestimmte Gruppe von Nutzern benötigt, um zu bestimmen, was in der Dokumentation hinzugefügt oder aus der Dokumentation entfernt werden sollte.

  1. THEMEN: Designs, Layouts, Designs und andere HTML-Funktionen wie die Suche richten sich nach den Anforderungen und Richtlinien der Community. In der Community-Bonding-Phase werde ich all das mit den Community-Mitgliedern besprechen.
  1. ZIEL STRECKEN: Als großes Ziel werde ich die Diagramme in der Dokumentation verbessern. Derzeit sind die Diagramme größtenteils einfache Schwarz-Weiß-Zeichnungen. Ich werde den Bildern mehr Farbe, Schattierungen, Skalierung, Einheitlichkeit und einen insgesamt ordentlicheren / professionelleren Look verleihen.

Zu diesem Zweck verwende ich „draw.io“ oder ein anderes Tool mit der Einwilligung des Mentors.

Als Proof of Concept habe ich eines der Diagramme in der Dokumentation mithilfe vondraw.io verbessert. Sie finden ihn hier: https://docs.google.com/document/d/1CUukNgwh6PvvUz9pOTOEEfi659HiyJvMHNyxumKZVfc/edit?usp=sharing

KONZEPT-NACHWEIS

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

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

Ich habe auch Webhooks im Code-Repository konfiguriert. Mithilfe dieser Webhooks werden die im Code-Repository vorgenommenen Änderungen auf der Website übernommen.

ZEITRAHMEN UND LIEFERBARKEITEN

COMMUNITY-BONDING-ZEITRAUM [17. August–13. September 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, um sicherzustellen, dass zu Beginn des Prozesses keine schlechten Entscheidungen getroffen werden. In dieser Phase werde ich mit den Mentoren und 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 das Hosting aller drei Themen oder drei verschiedene Websites zu diesen drei Themen gibt, werden während der Community-Bonding-Phase diskutiert.

DOKUMENTENTWICKLUNGSZEITRAUM [14. September–30. November 2020 ]

***Vom 14. September 2020 bis 20. September 2020 [WOCHE 1] Konvertierung des Dokumentinhalts in das erste 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 Handbuchs für Nutzer und Administratoren.

***Vom 28. September 2020 bis 4. Oktober 2020 [WOCHE 3] Umwandlung des Docbook-Inhalts in das erste Format für alle vier Kapitel des Programmer's Guide-Buchs.

***Vom 5. bis 11. Oktober 2020 [WOCHE 4] – Hosting beider PCP-Bücher auf der Website readthedocs. – Konvertierung der REST API-Dokumentation von der Manpage in das erste Format. Die Haupt-Landingpage wird in diesem Zeitraum abgedeckt. – Bloggen (über mein GSoD-Projekt) in den letzten drei und der aktuellen Woche

***Vom 12. Oktober 2020 bis 18. Oktober 2020 [WOCHE 5] Umwandlung des skalierbaren Zeitachsenindex in das erste Format. Der skalierbare Zeitachsenindex 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

***Vom 19. Oktober 2020 bis 25. Oktober 2020 [WOCHE 6] Umwandlung des Index der PMAPI Host Services in das erste Format. Der PMAPI Host Services-Index 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

***Vom 26. Oktober 2020 bis 1. November 2020 [WOCHE 7] – Falls in den letzten Wochen noch etwas übrig ist, werden alle Informationen zuerst abgedeckt. - Hosting der REST API-Dokumentation auf der readthedocs-Website - Bloggen (über mein GSoD-Projekt) in den letzten zwei Wochen und der aktuellen Woche

***Vom 2. bis 8. November 2020 [WOCHE 8] Umwandlung der Markdown-Inhalte in das erste Format für die Fotobücher.

***9. November 2020 bis 15. November 2020 [WOCHE 9] – Konvertieren der Markdown-Inhalte in das erste Format für die PBench-Leitfäden. - Hosting der PBench-Leitfäden auf der readthedocs-Website. - Bloggen (über mein GSoD-Projekt) für die letzte und die aktuelle Woche

***16. bis 22. November 2020 [WOCHE 10] – Suchfunktion auf der Indexseite für die Suche nach Inhalten im Namen der Website(s) implementiert – Beginn der Stretching-Ziele.

***23. November 2020 bis 30. November 2020 [WOCHE 11] – Verbesserung aller Diagramme in der Dokumentation. – Der letzte Blog meines GSoD-Projekts in der letzten und der aktuellen Woche – Prüfen, ob die Codebasis den Codierungsstandards entspricht oder nicht Falls nicht, passen Sie sie an die Standards an.

FINALISIERUNGSZEITRAUM [30. November bis 5. Dezember 2020 ]

  • Bleistift-Auszeit. Wir arbeiten an der endgültigen Einreichung und vergewissern uns, dass alles in Ordnung ist.
  • Einreichen der Projektberichte, auch als finale Arbeitsprodukte bezeichnet.
  • Einreichung der Projekterfolgsbewertungen und der Arbeitserfahrung mit den Mentoren