GenPipes-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:
GenPipes
Technischer Redakteur:
Sarah
Projektname:
GenPipes-Dokumente unter „Read The Docs“ einrichten
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

Ich schlage einen 3-Schritte-Plan vor, mit dem das Ziel der Einrichtung der GenPipes-Dokumentation zu „Read The Docs“ erreicht werden soll.

Schritt 1: Ansprechpartner

  • Vorhandene Dokumentation zu GenPipes als neuer Nutzer / Forscher prüfen

    • Fehlende Informationen oder Ungenauigkeiten identifizieren
    • Neue Dokumentthemen vorschlagen (falls erforderlich)
    • Eine Informationsarchitekturkarte entwerfen, die die Zielgruppe mit dem Schwerpunkt auf neuen Nutzenden anspricht.

    (Hinweis: Während dieses Schritts benötigen wir möglicherweise auch Informationen von GenPipes-Mentoren zu einem neuen GitHub-Repository, in dem Genpipes-Dokumente für RTD gehostet werden können. Dieses GitHub-Repository kann verwendet werden, um alle Dokumente in RTD-Build-Pipelines zu importieren. Dazu können Statistiken zu GenPipes-Repository-Regeln und Richtlinien zur Verwaltung von Dokumentquellen erforderlich sein, falls diese eingehalten werden müssen. Ansonsten können auch Standardmethoden verwendet werden. Für PoC kann ich auch ein Beispiel für die Einrichtung eines RTD-Repositorys in meinem GitHub-Konto demonstrieren. Beispiel: https://gpdocs.readthedocs.io/en/latest/ (dies ist ein Sampler, den ich für dieses Angebot erstellt habe)

  • Basierend auf der Überprüfung und Analyse im vorherigen Schritt erstellen Sie eine einfache Struktur aus vorgeschlagenen GenPipes-Dokumentationsstrukturen/-indexen und stellen Sie sie auf der RTD-Website bereit.

    • Dies umfasst die Erstellung des GitHub-Repositorys (z. B. mit Sphinx-Tools) und grundlegende Dokumentationsdateien
    • Dazu gehört auch ein neues Inhaltsverzeichnis, das sowohl neue Nutzende als auch erfahrene Anwendungsfälle für verschiedene Abschnitte / Informationsflüsse im Hinterkopf behält.

  • Überprüfung / Genehmigung für einfache Skeleton TOC-Elemente

    Während der GSoD-Bewertungsphase von GenPipes habe ich versucht, über dieses bei RTD gehostete Stichprobe einen Mehrwert für GenPipes zu schaffen. Bitte beachten Sie, dass dies nur zu Demo-Zwecken dient. Es handelt sich um einen geschützten Link, der noch nicht öffentlich in RTD aufgeführt ist. Unabhängig davon, ob ich in die engere Auswahl gekommen bin, kann diese Demo verwendet werden, um GenPipes RTD-Anstrengungen zu fördern. Ich habe bereits die Quellen im GitHub-Repository „c3g/GenPipes“ geprüft. Den Mentoren Rola und Hector gefiel es vorhin bei der Skype-Unterhaltung zum Teilen des Bildschirms. Deshalb dachte ich, dass GSoD Gods sie vielleicht auch sehen möchten. Im Moment ist es ein einfaches Raster, aber ich habe vor, es bis zum 30. Juli zu aktualisieren, wenn es die Zeit erlaubt.

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

Schritt 2: GenPipes-Dokument v0.9-Dokumentation erstellen

  • Finden Sie heraus, welche aktuellen oder vorhandenen GenPipes-Dokumente importiert, verknüpft oder in eine Sphinx-/erste Dokumentation konvertiert werden können, um auf RTD zu hosten. Berücksichtigen Sie dabei den GSoD-Zeitplan.

  • Konvertieren Sie die erkannten Dokumente bei Bedarf in das erste Format, erstellen Sie gegebenenfalls neue und verwenden Sie, was möglich bzw. relevant ist.

    • Importieren Sie dieses ursprüngliche Dokument als Proof of Concept in ReadTheDocs und hosten Sie es als geschütztes Repository. Erläutern Sie im Voraus, dass neue Nutzer die Originaldokumentation von GenPipes aufrufen, bis die Überprüfung bzw. der formale Wechsel genehmigt wird.

  • Überprüfen/Kurskorrektur/Aktualisierung

Schritt 3: Ersten Entwurf optimieren, überprüfen und veröffentlichen

  • Füllen Sie die Details der vorgeschlagenen neuen GenPipes-Dokumentstruktur in das GenPipes-Inhaltsverzeichnis ein: Fügen Sie neben den ersten zusätzlichen Dokumenten weitere Dokumente hinzu (GenPipes-Readme), Konzepte, Anleitungen usw.

  • Fügen Sie im Inhaltsverzeichnis eine klare Abgrenzung hinzu, um neue Nutzer, erfahrene GenPipes-Nutzer, GenPipes-Entwickler usw. anzusprechen.

  • Schlagen Sie vor, einen Arbeitsprozess mit Teilautomatisierung über RTD (Sphinx-Builds) darüber zu diskutieren, wie GenPipes-Dokumente gepflegt und von Nutzern bearbeitet werden können und ob C3G dies für externe Beitragende zulässt. Dies kann die Erstellung von Richtlinien für Dokumentaktualisierungen erforderlich machen, die den Programmierrichtlinien ähneln. Möglicherweise sind weitere Teilschritte erforderlich. Beispielsweise können Sie die Rechtschreibprüfung vor der PR-Genehmigung in GenPipes-Dokumenten automatisieren.

Bericht

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

Weitere Gedanken

In Zukunft (mehr als 3 Monate) und ggf. kann ich dazu beitragen, dass GenPipes langfristig erhalten bleiben. Oder schulen Sie bei Bedarf auch andere dafür. Anhand der Ergebnisse der ersten drei Monate können wir dies ermitteln.

Außerdem würde ich eine zusätzliche Idee für einen Projektvorschlag vorschlagen – die Erstellung eines 3-seitigen GenPipes-Briefings, das das Einstieg erleichtert. Heutzutage ist es für neue Nutzer schwierig, sich mit GenPipes vertraut zu machen, da die Dokumentation gut, aber verstreut und nicht für neue Nutzer geeignet ist. Ich bin mir nicht sicher, ob das innerhalb von drei Monaten möglich ist, aber ich würde es gerne versuchen.

Derselbe Vorschlag und seine Entstehung (Verlauf) können Sie sich auch unter https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing ansehen.