Aktuelle Phase:
Die Saison 2020 für Google Docs wurde am 15. März 2021 beendet. Siehe Zeitachse.
Diese Seite enthält Richtlinien für technische Redakteure, die wissen möchten, wie sie einen Projektbericht erstellen, wenn Sie Ihre Arbeit für die diesjährige Docs-Saison beendet haben.
Projektbericht einreichen
Sobald die Projektabschlussphase beginnt, können Sie Ihren Projektbericht einreichen. Dazu füllen Sie ein Formular aus, das im Abschnitt zur Projektabschlussphase des Leitfadens für technische Autoren verfügbar wird.
Informationen, die in den Projektbericht aufgenommen werden sollen
In diesem Abschnitt wird beschrieben, welche Informationen Sie in Ihrem Projektbericht angeben können. Es enthält Freitextfelder und Multiple-Choice-Fragen.
Link zu Ihren Aufgaben
Geben Sie einen Link an, der auf eine Beschreibung der von Ihnen geleisteten Arbeit verweist.
Der Link sollte auf ein Dokument verweisen, das eine kurze Beschreibung der geleisteten Arbeit, die Dokumentation, die das Open-Source-Projekt in sein Repository integriert hat, eine Zusammenfassung des aktuellen Status des Projekts und eine Liste der Herausforderungen und Erkenntnisse enthält.
Der Link wird in den Ergebnissen für die Staffel der Dokumente angezeigt, die auf der Website veröffentlicht werden. Die veröffentlichten Ergebnisse veranschaulichen die Arbeit, die Sie während des Programms ausgeführt haben. Die veröffentlichten Ergebnisse sind auch eine gute Möglichkeit, in Ihrem Lebenslauf auf Ihre Arbeit zurückzugreifen.
Sie sollten Ihren Link mit Ihrer beratenden Person teilen und um eine Überprüfung bitten, bevor Sie Ihren Projektbericht einreichen.
Anforderungen an deinen Projektbericht
Berücksichtigen Sie die folgenden Anforderungen:
- Der verlinkte Inhalt muss es einfach machen, das Werk zu identifizieren, das Sie während der „Staffel of Docs“ abgeschlossen haben, d. h. Ihre Änderungen oder die neue, von Ihnen verfasste Dokumentation.
- Die Arbeit sollte an einem stabilen Ort sein. Sie können die URL nach dem Senden nicht mehr ändern.
Eine andere Person sollte in der Lage sein, den Inhalt des Links (bzw. des Ziels) zu verwenden, um auf Ihrer Arbeit aufzubauen.
- Wenn Ihre Arbeit zu 100% abgeschlossen ist, sollten auch andere Personen sie verwenden können.
- Wenn Ihre Arbeit nicht zu 100% abgeschlossen ist, sollte klar sein, was noch zu tun ist.
Gute Beispiele für die Beschreibung Ihrer Arbeit
Sie müssen nicht alles (oder überhaupt) tun, aber hier sind einige Möglichkeiten, wie Sie die Anforderungen erfüllen können:
Erstellen Sie einen Blogpost, eine Webseite oder einen öffentlichen GitHub-Gist, in dem Sie Ihre Arbeit beschreiben und auf die von Ihnen durchgeführten Commits und die Repositories verweisen, an denen Sie gearbeitet haben. Wenn es für das Projekt noch zu tun gibt, fügen Sie eine Beschreibung dieser Arbeit hinzu. Sie können auch Highlights oder herausfordernde Stücke teilen.
Dies ist die beste Option, da Sie damit ganz einfach viele Informationen hinzufügen können. Das ist gut, weil Ihre Arbeit so klar zeigt und es für andere leicht ist, Ihren Beitrag zu nutzen und zu verstehen.
Wenn Sie GitHub verwenden und Ihre gesamte Arbeit von einer einzigen Pull-Anfrage abgedeckt wird, können Sie diesen Link verwenden.
- Achten Sie darauf, dass die Beschreibung der Pull-Anfrage detailliert ist.
- Achten Sie darauf, dass in der Beschreibung deutlich darauf hingewiesen wird, dass es sich um "Season of Docs" handelt.
- Wenn die Pull-Anfrage nach dem Ende der Datei „Season of Docs“ noch weiter bearbeitet werden muss, muss im letzten Season of Docs-Commit darauf hingewiesen werden.
- Diese Methode zur Bereitstellung eines Projektberichts hat den Vorteil, dass das Änderungsprotokoll, eine Liste der Commits und die Kommentare zur Überprüfung an einem Ort verfügbar sind.
Wenn Ihr GitHub-Repository nur für „Season of Docs“ verwendet wird, fügen Sie eine Infodatei mit den Details zu Ihrer Arbeit hinzu.
Erstellen Sie in Google Drive einen öffentlichen Ordner und fügen Sie alle von Ihnen erstellten Patches ein.
Erstellen Sie mit Google Tabellen eine öffentliche Tabelle und listen Sie alle Ihre Commits auf.
Stellen Sie in einer öffentlichen Problemverfolgung einen Link zu einem einzelnen Problem bereit, das klare Verweise auf Ihre Arbeit und alles andere enthält, was angemessen ist. Das Problem sollte Ihre gesamte Arbeit erfassen. Achten Sie darauf, dass im Problem alle Commits aufgelistet sind oder dass sie auf andere Weise leicht zu finden sind.
Erstellen Sie einen Link zu einer einheitlichen oder Kontextdifferenz Ihrer Änderungen. Vergessen Sie nicht, eine Überschrift einzufügen, die den Namen Ihres Projekts für technisches Schreiben und Ihre Identität enthält, damit sie für andere nützlich ist.
Schlechte Beispiele für eine Beschreibung deiner Arbeit
Vermeiden Sie Folgendes:
- Erstellen Sie eine Verknüpfung zu einer Tarball- oder ZIP-Datei, die den Quellcode des gesamten Projekts oder Ihr Arbeitsverzeichnis enthält.
- Link zum Anfang des primären Quell-Repositorys des Projekts. Wenn Sie beispielsweise an Cpython arbeiten, ist dieser Link nicht hilfreich: https://github.com/python/cpython.
- Erstellen Sie einen Link zu Ihrem Klon des Quell-Repositorys des Projekts. Dadurch ist es schwer zu erkennen, was Ihre Änderungen sind, da Ihre Arbeit mit der Arbeit anderer Personen vermischt ist.
- Einen Link zu Ihrer Projektbeschreibung finden Sie auf der Website für die Season of Docs.
Für die beratenden Personen
Helfen Sie Ihrem technischen Redakteur, einen ordnungsgemäßen Projektbericht zu erstellen. Dies ist wichtig, bevor Sie Ihre eigene Bewertung der Arbeit des technischen Redakteurs erstellen.
Folgende Voraussetzungen müssen erfüllt sein:
- Die Einreichung muss die oben beschriebenen Anforderungen erfüllen.
- Die Einreichung muss eine Beschreibung der geleisteten Arbeit, die erfüllten Anforderungen und die Gründe für alle getroffenen spezifischen Entscheidungen enthalten.
Der Grundgedanke von „Season of Docs“ besteht nicht darin, dass technische Redakteure sehr viele Dokumentationen herausarbeiten. Es ist wichtig, dass die Arbeit für das Hosting-Open-Source-Projekt potenziell nützlich ist.