GenPipes-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:
GenPipes
Technischer Redakteur:
shaloo
Projektname:
GenPipes-Dokumente bei „Read The Docs“ einrichten
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

Ich schlage einen dreistufigen Plan vor, um die GenPipes-Dokumentation auf „Read The Docs“ einzurichten.

Schritt 1: PoC

  • Vorhandene Dokumentation von GenPipes als neuer Nutzer / Forscher ansehen

    • Fehlende Informationen und Ungenauigkeiten identifizieren
    • Neue Themen für das Dokument vorschlagen (falls erforderlich)
    • Erstellen Sie eine Informationsarchitektur-Map, die auf die Zielgruppe ausgerichtet ist, mit Schwerpunkt auf neuen Nutzern.

    Hinweis: Bei diesem Schritt benötigen wir möglicherweise auch die Unterstützung von GenPipes-Mentoren bei der Einrichtung eines neuen GitHub-Repositories, in dem GenPipes-Dokumente für RTD gehostet werden können. Mit diesem GitHub-Repository können alle Dokumente in RTD-Build-Pipelines importiert werden. Dazu sind möglicherweise Informationen zu den GenPipes-Repository-Regeln und Richtlinien zur Verwaltung von Dokumentquellen erforderlich, sofern diese eingehalten werden müssen. Andernfalls können Standard-Assets verwendet werden. Außerdem kann ich für das Proof of Concept eine Beispieleinrichtung eines RTD-Repositorys mit meinem GitHub-Konto demonstrieren, z. B. https://gpdocs.readthedocs.io/en/latest/. Dies ist ein Beispiel, das ich für diesen Vorschlag erstellt habe.

  • Erstellen Sie anhand der Überprüfung und Analyse im vorherigen Schritt ein einfaches Skelett der vorgeschlagenen GenPipes-Dokumentationsstruktur / des Index und stellen Sie es auf der RTD-Website bereit.

    • Dazu gehört das Erstellen eines GitHub-Repositorys (z. B. mit Sphinx-Tools) und grundlegende Dokumentationsdateien.
    • Dazu gehört auch die Erstellung eines neuen Inhaltsverzeichnisses, das sowohl für neue als auch für erfahrene Nutzer für verschiedene Abschnitte und Informationsflüsse geeignet ist.

  • Barebones-Skelett-TOC prüfen / genehmigen lassen

    Während der GSoD-Bewertungsphase von GenPipes habe ich versucht, mit diesem bei RTD gehosteten Beispiel einen Mehrwert für GenPipes zu schaffen. Hinweis: Dieser Link ist nur zu Demozwecken gedacht und noch nicht öffentlich auf RTD gelistet. Unabhängig davon, ob ich in die engere Auswahl komme, kann diese Demo dazu verwendet werden, die RTD-Bemühungen von GenPipes zu beschleunigen. Ich habe die Quellen bereits in das GitHub-Repository c3g/GenPipes eingecheckt. Den Mentoren Rola und Hector hat es bei der Skype-Videokonferenz gefallen und ich dachte, dass die GSoD-Götter es vielleicht auch sehen möchten. Es ist derzeit nur ein Rohgerüst, aber ich werde es bis zum 30. Juli aktualisieren, sobald ich Zeit dazu habe.

https://genpipes.readthedocs.io/en/latest/

Schritt 2: DocSet für GenPipes Doc v0.9 erstellen

  • Identifizieren Sie, welche aktuellen oder vorhandenen GenPipes-Dokumente importiert, verknüpft oder in Sphinx-/rst-basierte Dokumentation für das Hosting auf RTD konvertiert werden können, wobei die Zeitpläne für die GSoD berücksichtigt werden müssen.

  • Konvertieren Sie die identifizierten Dokumente bei Bedarf in das erste Format, erstellen Sie gegebenenfalls neue und verwenden Sie alle möglichen / relevanten Elemente wieder.

    • Importieren Sie dieses ursprüngliche Dokument als Proof of Concept in ReadTheDocs und hosten Sie es dort als geschütztes Repository. Fügen Sie einen Hinweis hinzu, in dem Sie neuen Nutzern empfehlen, sich an die Originaldokumentation von GenPipes zu wenden, bis die Überprüfung/offizielle Umstellung genehmigt wurde.

  • Review/course-correct/update

Schritt 3: Ersten Entwurf im RTD-Format überarbeiten, überprüfen und veröffentlichen

  • Geben Sie Details zur vorgeschlagenen neuen GenPipes-Dokumentstruktur in die GenPipes-Inhaltsübersicht ein. Fügen Sie neben den ersten Dokumenten (GenPipes-Readme) weitere Dokumente wie Konzepte, Anleitungen usw. hinzu.

  • Füge in den Nutzungsbedingungen deutliche Abgrenzungen hinzu, um neue Nutzer, erfahrene GenPipes-Nutzer, GenPipes-Entwickler usw. anzusprechen.

  • Einen Arbeitsablauf mit teilweiser Automatisierung über RTD (Sphinx-Builds) vorschlagen und besprechen, wie das GenPipes-Dokumentpaket von Nutzern gepflegt und bearbeitet werden kann und ob C3G dies für externe Mitbearbeiter von Dokumenten zulässt. Dies kann die Erstellung einiger Richtlinien für Dokumentaktualisierungen erfordern, ähnlich wie bei Codierungsrichtlinien. Eventuell sind weitere Teilschritte erforderlich. Beispiel: Automatische Rechtschreibprüfung vor der PR-Genehmigung in GenPipes-Dokumenten

Bericht

Erstellen Sie abschließend einen Bericht für GSoD, der auf Erfahrungen, Protokollen und Feedback von Mentoren basiert.

Weitere Überlegungen

In Zukunft (nach Ablauf der 3 Monate) kann ich GenPipes bei Bedarf auch längerfristig unterstützen. Bei Bedarf können Sie auch andere entsprechend trainieren. Anhand der Ergebnisse, die wir in den ersten drei Monaten erzielt haben, können wir dies feststellen.

Außerdem würde ich eine zusätzliche Projektvorschlagsidee vorschlagen: Erstellen Sie ein dreiseitiges GenPipes-Briefing, das das Onboarding erleichtert. Derzeit müssen neue Nutzer viele Hürden überwinden, bevor sie mit GenPipes beginnen können, da die Dokumentation zwar gut, aber unübersichtlich und für neue Nutzer nicht geeignet ist. Ich bin mir nicht sicher, ob das innerhalb von drei Monaten möglich ist, aber ich möchte es versuchen.

Dieser Vorschlag und seine Entstehungsgeschichte (Verlauf) können auch unter https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing eingesehen werden.