Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- GenPipes
- Technischer Redakteur:
- Shaloo
- Projektname:
- GenPipes-Dokumente unter „Read The Docs“ einrichten
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Ich schlage einen 3-Schritte-Plan vor, um die GenPipes-Dokumentation für „Read The Docs“ einzurichten.
Schritt 1: Ansprechpartner
Vorhandene Dokumentation zu GenPipes als neue Nutzer / Forscher überprüfen
- Fehlende Informationen und Ungenauigkeiten ermitteln
- Neue Themen für Dokumente vorschlagen (falls erforderlich)
- Eine Informationsarchitekturkarte entwerfen, die auf die Zielgruppe ausgerichtet ist und sich vor allem auf neue Nutzer konzentriert.
(Hinweis: In diesem Schritt 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. Mit diesem GitHub-Repository können alle Dokumente in RTD-Build-Pipelines importiert werden. Dazu sind möglicherweise Einblicke in die GenPipes-Repository-Regeln und Richtlinien zur Verwaltung von Dokumentquellen erforderlich, falls diese eingehalten werden müssen. Andernfalls können Standard-Creatives verwendet werden, afaik. Als PoC kann ich mit meinem GitHub-Konto auch ein Beispiel für die Einrichtung eines RTD-Repositorys testen. Beispiel: https://gpdocs.readthedocs.io/en/latest/. Das ist ein Sampler, den ich für dieses Angebot erstellt habe.
Basierend auf der Überprüfung und Analyse im vorherigen Schritt erstellen Sie ein einfaches Skelett der vorgeschlagenen GenPipes-Dokumentationsstruktur/-indexierung und stellen es auf der RTD-Website bereit
- Dies umfasst die Erstellung des GitHub-Repositorys (z. B. mit Sphinx-Tools) und grundlegende Dokumentationsdateien
- Dazu gehört auch eine neue Inhaltsübersicht, die sowohl neue Nutzende als auch erfahrene Anwendungsfälle für verschiedene Abschnitte / Informationsflüsse im Hinterkopf behält.
Gesamtinhaltsinhalt prüfen / Genehmigung einholen
Während der Bewertungsphase von GenPipes GSoD habe ich versucht, mit diesem von RTD gehosteten Beispiel einen Mehrwert für GenPipes zu schaffen. Bitte beachten Sie, dass dieser Link nur zu Demozwecken dient. Er ist geschützt und noch nicht im RTD öffentlich gelistet. Egal, ob ich in die engere Auswahl gekommen bin, kann diese Demo dazu verwendet werden, GenPipes-Förderungsübungen voranzutreiben. Ich habe bereits die Quellen im GitHub-Repository für c3g/GenPipes geprüft. Den Mentoren Rola und Hector gefiel es in der Skype-Diskussion zum Teilen des Bildschirms. Deshalb dachte ich, dass GSoD Gods es vielleicht auch sehen möchten. Im Moment ist es ein absolutes Grundgerüst, aber ich habe vor, es bis zum 30. Juli zu aktualisieren, sobald es die Zeit erlaubt.
https://genpipes.readthedocs.io/en/latest/
Schritt 2: Dokumenterstellung mit GenPipes-Dokument v0.9 erstellen
Finden Sie heraus, welche aktuellen oder vorhandenen GenPipes-Dokumente importiert, verknüpft oder in eine Sphinx-/erste Dokumentation konvertiert werden können, um sie im Rahmen von RTD zu hosten. Berücksichtigen Sie dabei den GSoD-Zeitplan.
Konvertieren Sie die identifizierten Dokumente bei Bedarf in das erste Format, erstellen Sie gegebenenfalls neue und verwenden Sie alle möglichen / relevanten Dokumente wieder.
- Importieren Sie dieses ursprüngliche Dokument als Proof of Concept in ReadTheDocs und hosten Sie es als geschütztes Repository. Weisen Sie neuen Nutzern im Vorfeld darauf hin, dass sie die Originaldokumentation von GenPipes aufrufen müssen, bis die Überprüfung bzw. der formale Wechsel genehmigt wird.
Überprüfen/Kurs korrigieren/aktualisieren
Schritt 3: Ersten Entwurf optimieren, überprüfen und veröffentlichen
Geben Sie Details zur vorgeschlagenen neuen GenPipes-Dokumentstruktur in das GenPipes-Inhaltsverzeichnis ein – Fügen Sie neben den ersten Dokumenten weitere Dokumente hinzu (GenPipes-Readme), Konzepte, Anleitungen usw.
Fügen Sie im Inhaltsverzeichnis einen klaren Abschluss hinzu, um neue Nutzer, erfahrene GenPipes-Nutzer, GenPipes-Entwickler usw. anzusprechen.
Schlagen Sie vor, besprechen Sie einen Arbeitsprozess mit Teilautomatisierung über RTD (Sphinx-Builds), wie das GenPipes-Dokument verwaltet und von Nutzern bearbeitet werden kann und ob C3G dies für externe Beitragende zulässt. Dies kann für Dokumentaktualisierungen, die den Programmierrichtlinien ähneln, das Erstellen von Richtlinien erforderlich machen. Möglicherweise sind weitere Teilschritte erforderlich. Beispielsweise können Sie in GenPipes-Dokumenten die Rechtschreibprüfung vor der PR-Genehmigung automatisieren.
Melden
Erstellen Sie schließlich einen Bericht für GSoD auf der Grundlage von Erfahrungen, Protokollen und Feedback von Mentoren.
Weitere Gedanken
In Zukunft (mehr als 3 Monate) kann ich dazu beitragen, dies für GenPipes langfristig beizubehalten. Oder schulen Sie bei Bedarf 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 dreiseitigen GenPipes-Briefings, das das Einstieg erleichtert. Heutzutage muss ein neuer Nutzer viele Herausforderungen meistern, bevor er GenPipes nutzen kann, da die Dokumentation gut, aber verstreut ist und nicht für neue Nutzer geeignet ist. Ich bin mir nicht sicher, ob das innerhalb von 3 Monaten möglich ist, aber ich würde es gerne versuchen.
Derselbe Vorschlag und seine Entstehung (Verlauf) können auch unter https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing eingesehen werden.