Aktuelle Phase:
Dokumentationsentwicklung. Siehe Zeitachse.
Nutzen Sie dieses Beispiel, um Ihren eigenen Fallstudienbericht zu erstellen.
PicklePlus: Das GloriousPickle-Beitragstool dokumentieren
Organisation oder Projekt: Glorious Pickle Link zur Hauptwebsite Ihrer Organisation oder Ihres Projekts hier
Beschreibung der Organisation: GloriousPickle (aktuelle Version 1.2.3, erste Version im Jahr 2009) ist eine vom MIT lizenzierte Bibliothek zur einfachen Berechnung des perfekten Verhältnisses von Salz, Zucker, Essig und Gewürzen für alle möglichen eingelegten Gemüsesorten, von einer einzelnen Gurkenbaby bis hin zu Containerschiffen.
Autoren: optional: Autoren der Fallstudie auflisten; gegebenenfalls Nutzernamen verwenden
Problembeschreibung/Zusammenfassung des Vorschlags
Welches Problem wollten Sie mit der neuen oder verbesserten Dokumentation lösen? Verlinke nach Möglichkeit die Angebotsseite auf deiner Projektwebsite.
Das Hinzufügen von Zutaten zur Zutatendatenbank des GloriousPickle-Tools ist zeitaufwendig und kompliziert und das Tool hat keine gute Dokumentation. Viele angehende Beitragende haben keine Erfahrung mit Git oder mit Pull-Anfragen. Das bedeutet, dass GloriousPickle erhebliche Lücken in unseren Zutatendaten aufweist und unser Tool weniger nützlich macht. Durch die Verbesserung der Dokumentation für das Hinzufügen neuer Zutaten möchten wir neue Beitragende und das Einlegen neuer Zutaten fördern.
Projektbeschreibung
Angebot erstellen
Wie sind Sie auf Ihren Vorschlag für die Staffel von Google Docs gekommen? Welchen Prozess hat Ihre Organisation genutzt, um sich für eine Idee zu entscheiden? Wie haben Sie Feedback eingeholt und umgesetzt?
Die GloriousPickle PickleDocs SIG hörte in einem Tweet der Open-Source-Programme-Niederlassung von Google von dem Programm "Google Season of Docs". Die SIG besprach das Programm bei ihrem zweiwöchentlichen Meeting und erklärte sich bereit, einen Vorschlag zu unterbreiten. Zwei Mitglieder der SIG (@KimChiCook und @Dillicious) haben sich bereit erklärt, an dem Entwurf des Antrags zur Prüfung im nächsten Meeting mitzuarbeiten.
Nachdem die PickleDocs SIG dem Angebotsentwurf zugestimmt hatte, wurde eine E-Mail an das übergeordnete Projekt gesendet und um Feedback gebeten. 14 Community-Mitglieder gaben Feedback, darunter @GloriousPicklePat, der Betreuer der API zum Hinzufügen von Zutaten. @GloriousPicklePat hat sich während des Programms als Ressource gemeldet.
Nach Diskussion und Berücksichtigung des erhaltenen Feedbacks wurde der Vorschlag dem Lenkungsausschuss für das GloriousPickle-Projekt zur Abstimmung gesendet. Alle fünf Mitglieder der GPPSC haben mit +1 für die Einreichung des Vorschlags und der Bewerbung abgestimmt und @VinegarViv erklärte sich bereit, bei der Erstellung des Open Collective-Kontos zu helfen, das für die Teilnahme am Programm und die Überwachung von Zahlungen erforderlich ist.
Budget
Fügen Sie Ihrem Budget einen kurzen Abschnitt hinzu. Wie haben Sie die Arbeit geschätzt? Gab es unerwartete Kosten? Haben Sie am Ende weniger als die Fördergelder ausgegeben? Haben Sie die Mittel richtig zugewiesen oder waren einige Positionen mehr/weniger/unnötig im Budget? Hattest du außerhalb von Google Season of Docs weitere Mittel, die du nutzen konntest?
Zwei Mitglieder der GloriousPickle PickleDocs SIG haben als technische Redakteure gearbeitet (einer in Europa und einer in Argentinien). Sie halfen uns, die Arbeit einzuschätzen, ähnliche Projektbudgets zu finden und die zuvor geleisteten Angebotsentwürfe zu vergleichen. Außerdem waren 1.000$an unbeschränktem Sponsorship-Geld aus der PicklePals-Konvention von 2019 übrig, die wir dem Projekt zugewiesen haben.
Unvorhergesehene Ausgaben bestand darin, unsere technische Redakteurin bei der Anmietung eines WLAN-Hotspots zu unterstützen, da sie sich in einem Gebiet befanden, das von Waldbränden betroffen war und den Internetzugang vor Ort verloren hatte. Außerdem versendeten wir weniger T-Shirts an die Teilnehmer, als wir geplant hatten, sodass es ausgeglichen wurde.
Außerdem haben wir uns entschieden, eine Mitwirkende bei GloriousPickle, @Piccalily, die früher eine professionelle Copyeditorin in ihrem Leben ohne Pickle war, für die Lektüre und das Korrekturlesen der Dokumentation des technischen Redakteurs zu bezahlen.
Teilnehmer
Wer hat an diesem Projekt gearbeitet (Nutzernamen verwenden, falls die Teilnehmer dazu aufgefordert werden)? Wie haben Sie Ihre technische Redakteurin gefunden und eingestellt? Wie haben Sie andere Freiwillige oder bezahlte Teilnehmer gefunden? Welche Rollen hatten sie? Ist jemand ausgestiegen? Was haben Sie über Rekrutierung, Kommunikation und Projektmanagement gelernt?
Das Kernteam, das an diesem Projekt arbeitete, war:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (Texteditor)
- @GherKen, @VinegarViv (Admin-Hilfe, GPPSC)
- @BBChips, @GloriousPicklePat (Fachleute)
- Sam Scribe (Technischer Redakteur)
Sam Scribe wurde in der GitHub-Repository-Liste von Google Season of Docs gefunden. Wir waren der Meinung, dass ihre Erfahrungen (Sam hatte für ein kulinarisches Magazin gearbeitet und Dokumentationen für Websites geschrieben) gut zu unserem Projekt passten. Sam nimmt am zweiwöchentlichen Telefonat von PickleDocs SIG teil, sprach mit uns über das Projekt und machte mehrere sehr wertvolle Vorschläge, die wir in den Vorschlag aufgenommen haben. Wir haben auch zwei weitere technische Redakteure kontaktiert, die uns über die Netzwerke unserer SIG-Mitglieder bekannt waren, aber keiner war während des Programms erreichbar.
Da sich Sams Zeitzone nur ein paar Stunden mit den meisten Mitgliedern der PickleDocs SIG überschnitt, haben wir in unserem Diskussionsforum für Picklers angerufen, die sich in Sams Zeitzone aufhielten und mit dem Prozess zum Hinzufügen von Zutaten vertraut waren. @BBChips hat sich bereit erklärt, Samuel Fragen zu beantworten und bei Bedarf andere Experten zu finden. @GloriousPicklePat meldete sich auch freiwillig, um Sam zu helfen, die zugrunde liegende Architektur des Tools und mögliche Fehlermeldungen der API zu verstehen, und gab Hilfe von GitHub und Git zur Verfügung.
Leider musste @VinegarViv in der Mitte des Programms aus persönlichen Gründen das Projekt verlassen. GPPSC-Mitglied @GherKen meldete sich, um administrative und zahlungsbezogene Fragen zu beantworten.
Nachdem einige Fragen verpasst wurden (GloriousPickle verwendet eine kostenlose Slack-Instanz und manchmal läuft die Diskussion so schnell ab, dass Unterhaltungen aufgrund des Limits für die rollende Archivierung verloren gehen), haben wir gelernt, dass wir eine Liste laufender Fragen in einem gemeinsamen Dokument führen sollten (wir haben ein freigegebenes Google-Dokument verwendet). Die Mitglieder von PickleDocs SIG haben sie vor jedem Meeting überprüft und darauf geachtet, vor Ende der Besprechung die Antworten zu erhalten. Sam konnte @BBChips bei dringenden Fragen direkt kontaktieren.
Wir waren sehr zufrieden mit Sam und Sam und haben nicht nur die GloriousPickle-Dokumentation aktualisiert, sondern sind auch selbst ein begeisterter Pickler geworden!
Zeitachse
Gib einen kurzen Überblick über den Zeitplan deines Projekts. Gib dabei das geschätzte Enddatum oder zwischenzeitliche Meilensteine an, wenn das Projekt noch andauert.
Während wir auf die Ankündigung der teilnehmenden Organisationen im Google Season of Docs-Programm warteten, suchten die Mitglieder von PickleDocs SIG nach früheren Arbeiten, von denen wir dachten, dass sie für Sam hilfreich sein könnten. Im Laufe eines Monats haben wir einige Notizen zu einer früheren Initiative zur Aktualisierung der stagnierten Dokumentation gefunden. Außerdem haben wir Teile der Materialien zur Prüfung der Reife der Dokumentation im Google Opendocs-Repository durchgearbeitet.
Nachdem wir die gute Nachricht erhalten hatten, dass wir für die Google Season of Docs ausgewählt wurden, trafen sich Sam und die PickleDocs SIG und erarbeiteten einen groben Zeitplan:
| Phase | Abgeschlossen von |
|---|---|
| Audit der Dokumentation ansehen | 7. Mai |
| Anwendungsfälle für Reibungsprotokoll 3 | 14. Mai |
| Reibungslose Protokolle mit @GloriousPicklePat und @BBChips prüfen, Fragen beantworten | 28. Mai |
| Erster Entwurf von aktualisierten Dokumenten – Anwendungsfall 1 | 25. Juni |
| Anwendungsfall 1 Entwurf geprüft von @GloriousPicklePat und @KimChiCook | 2. Juli |
| Erster Entwurf von aktualisierten Dokumenten – Anwendungsfall 2 | 2. Juli |
| Entwurf für Anwendungsfall 2 geprüft von @GloriousPicklePat und @Dillicious | 9. Juli |
| Erster Entwurf von aktualisierten Dokumenten – Anwendungsfall 3 | 9. Juli |
| Entwurf von Anwendungsfall 3, geprüft von @Dillicious und @KimChiCook | 16. Juli |
| Alle Abfragen wurden für alle Anwendungsfälle beantwortet | 30. Juli |
| Der größte Teil von PickleDocs SIG war vom 1. bis 20. August im Urlaub | -- |
| Mit dem Testen neuer Dokumente in der Community beginnen (Dokumente, die als Entwürfe auf der GloriousPickle-Website veröffentlicht wurden) | 21. August |
| Testfeedback berücksichtigt | 10. September |
| Neue Dokumente kopieren und Korrekturlesen | 17. September |
| Entwurfsstatus von Dokumenten entfernt, Dokumente offiziell eingeführt | 28. September |
| Prozess zum Aktualisieren der Dokumentation erstellt | 1. November |
| Diese Fallstudie hat | 8. November |
| Fallstudie eingereicht | 16. November |
In unserem Angebotsbudget hatten wir geschätzt, dass die technische Redaktion 10 bis 15 Stunden pro Woche mit der Arbeit an unserem Projekt verbringen würde. Sam hat Aufzeichnungen über die verbrachte Zeit und durchschnittlich 11,5 Stunden pro Woche geführt.
Ergebnisse
Was wurde erstellt, aktualisiert oder anderweitig geändert? Geben Sie Links zu veröffentlichten Dokumentationen an, sofern verfügbar. Gab es im Angebot Liefergegenstände, die nicht erstellt wurden? Führen Sie auch diese auf.
Drei wichtige Anwendungsfälle wurden mit umfassenden Nutzeranleitungen dokumentiert:
GloriousPickle eine neue Zutat hinzufügen
So fügst du GloriousPickle eine Zutat für Varianten hinzu
Eine Zutat in GloriousPickle aktualisieren oder korrigieren
Diese Leitfäden enthielten auch neue Vorlagen für Pull-Anfragen, um Beiträge einfacher zu gestalten.
Während des Projekts erstellte Sam ein kleines Pickle-Glossar mit von ihm Gelernten, das auch auf der GloriousPickle-Projektwebsite veröffentlicht wurde.
Wir haben unserem Projekt-Wiki Anweisungen zur Aktualisierung dieser Anleitungen für Nutzer hinzugefügt.
Wir hatten einen Spickzettel für Mitwirkende, die neu bei GitHub sind, erstellt, um ihnen bei der Verwendung unserer Prozesse und Tools zu helfen. Nachdem wir uns die verfügbaren Ressourcen angesehen hatten, konnten wir stattdessen eine andere Projektübersicht erstellen.
Messwerte
Welche Messwerte haben Sie ausgewählt, um den Erfolg des Projekts zu messen? Konnten Sie diese Metriken erfassen? Korrelieren die Metriken gut oder schlecht mit den Ergebnissen, die Sie für das Projekt sich wünschen? Haben sich Ihre Messwerte seit dem Vorschlag geändert?
In unserem Vorschlag haben wir zwei Metriken vorgeschlagen:
- Anzahl der auf Zutaten bezogenen Pull-Anfragen
- Anzahl der Pull-Anfragen von neuen Beitragenden
Im September (dem ersten vollen Monat seit der Veröffentlichung des Dokumentationsentwurfs) stiegen die Pull-Anfragen für die Zutaten um 5% an (von 20 im August auf 21 im September). Außerdem gab es drei neue Beitragende, die insgesamt vier Pull-Anfragen stellten (im Gegensatz zu zwei neuen Beitragenden, die zwei Pull-Anfragen im August gestellt haben). Wir planen, diese Messwerte monatlich zu erfassen.
Ab dem 1. Januar erfassen wir außerdem die Anzahl der Beitragenden, die insgesamt mehr als drei Beiträge geleistet haben, und beginnt vierteljährlich, nachdem die Dokumentation veröffentlicht wurde.
Wir sind der Meinung, dass diese neue Dokumentation dazu beigetragen hat, dass neue Beitragende die GloriousPickle-Zutatendatenbank hinzufügen können. Ein neuer Mitwirkender erwähnte im Kommentar seiner PR, dass er es schon einmal ausprobiert hatte, das Update aber nicht abgeschlossen hatte, weil er den Prozess nicht verstanden hatte.
Analyse
Was hat gut funktioniert? Was ist unerwartet? Vor welchen Hürden oder Rückschlägen sind Sie gekommen? Ist Ihr Projekt für Sie erfolgreich? Warum bzw. warum nicht? (Falls es noch zu früh ist, um das zu beurteilen, erklären Sie, wann Sie davon ausgehen, den Erfolg Ihres Projekts beurteilen zu können.)
Wir sind sehr zufrieden mit dem Ergebnis des Google-Projekts "Season of Docs" und bezeichnen es als Erfolg. Die neue Dokumentation ist klar und hilfreich, und die Anzahl der Pull-Anfragen, die mit den Zutaten zusammenhängen, sowie die Anzahl der Pull-Anfragen von neuen Beitragenden ist bereits gestiegen.
Wir waren auch froh, dass fast die gesamte GloriousPickle-Community an der Umfrage teilgenommen hat, indem sie Feedback zum ursprünglichen Vorschlag gab und die neuen Dokumente im Entwurfsformat testete.
Wir hatten ein paar unerwartete Hürden dabei – wir waren dankbar, dass die Waldbrände in Sams Bundesland nicht mehr Schaden verursachten als ein Internetausfall. Außerdem schade, dass wir @VinegarViv aus dem Projekt verloren haben. Wir wünschen ihr und ihrer Familie alles Gute und hoffen, sie bald wiederzusehen.
Als Sam mit der Arbeit an der Dokumentation begann, wurde uns nicht klar, wie viele Begriffe und Akronyme im Zusammenhang mit Essiggurken nicht bekannt waren. Sam hat sich jedoch zum Ziel gesetzt, eine Liste aller unbekannten Begriffe zu erstellen und sie durch eigene Recherchen zu definieren und die Community-Mitglieder um Erklärungen und Verweise zu bitten. Dieses Pickle-Glossar ist eine große Hilfe dabei, in Zukunft mehr Menschen in der Pickle-Community willkommen zu heißen.
Zusammenfassung
Fassen Sie Ihre Projekterfahrung in 2 bis 4 Absätzen zusammen. Heben Sie hervor, was Sie gelernt haben und was Sie in Zukunft anders machen würden. Welchen Rat würden Sie anderen Projekten geben, die ein ähnliches Problem mit der Dokumentation lösen möchten?
Kurz gesagt: Unsere Erfahrung war eindringlich. Wir haben unsere Liefergegenstände in der Dokumentation erreicht und unsere Metriken scheinen mit unseren Zielen zu übereinstimmen.
Ein großer Teil des Erfolgs dieses Projekts war unser Glück, dass wir mit unserem technischen Redakteur Sam Scribe zusammengearbeitet haben. [Ich habe das nicht geschrieben – Sam] Sam hatte zwar weder Erfahrung mit Pickling noch Erfahrung mit GitHub, als erfahrener technischer Redakteur fühlte er sich aber wohl dabei, in ein neues Fachgebiet einzutauchen, Fragen zu stellen und zu recherchieren. Sam nahm nicht nur unsere Projekttools (wir verwenden eine Kanban-Tafel, um den Überblick über die Arbeit zu behalten), sondern auch unsere Gurkenwitze auf. Wir sind sehr froh, dass Sam in der Gemeinde auf den Pickling gestoßen ist und wir ihn in unserer Gemeinde „abgefüllt“ haben.
Wir empfehlen anderen Projekten:
- Halten Sie Ihre Angebote klein und übersichtlich. (Ursprünglich wollten wir die Dokumentation für die Verwendung unseres Schätzers mit industriellen Einmachmaschinen in unser Angebot aufnehmen, haben sie aber nur ausgelassen, weil eines unserer Community-Mitglieder, die sich intensiv mit der Open-Source-Software für Gurkenmaschinen beschäftigen, im Laufe des Programms seine Doktorarbeit schrieb.) Am Ende hatten wir mehr als genug Arbeit, um Sam zu halten.
- Nutze dein Netzwerk, wenn du nach einem technischen Redakteur suchst. Bitte alle Personen in deiner Community um Empfehlungen. Obwohl wir Sam über den GitHub-Kanal von Google Season of Docs gefunden haben, waren wir zuversichtlich, mit ihnen zusammenzuarbeiten, da wir während des Bewerbungszeitraums mit mehreren Personen gesprochen haben.
- Begrüße deine technische Redakteurin in deiner Community! Sam erzählte uns, dass es aufgrund der Begeisterung der GloriousPicklers leicht war, Fragen zu stellen.
- Unterstützen Sie technische Redakteure dabei, sich Open-Source-Kenntnisse anzueignen. Sam hatte Git noch nie verwendet, aber nach ein paar Tutorials konnte er sich schnell einarbeiten. Zuerst war Sam besorgt darüber, wie viel Feedback von der Community kommen könnte und wie er es umsetzen könnte. Aber das „grobe Konsensmodell“ unserer Community (der Konsens wird erreicht, wenn alle Probleme angegangen sind, aber nicht unbedingt berücksichtigt werden) sorgten dafür, dass er mit seinem technischen Schreibwissen souverän auf Kritik eingehen konnte.
Anhang
Wenn Sie weitere Materialien haben, auf die Sie verlinken möchten, z. B. wenn Sie einen Vertrag über die Zusammenarbeit mit Ihrem technischen Redakteur abgeschlossen haben, den Sie teilen möchten, Vorlagen für Ihr Dokumentationsprojekt oder andere offene Dokumentationsressourcen, können Sie diese hier auflisten und verlinken. Im Anhang finden Sie außerdem Links zu Dokumentationstools oder Ressourcen, die Sie verwendet haben, oder einen Ort, an dem Sie Danksagungen oder Danksagungen einfügen können, die möglicherweise nicht in die obigen Abschnitte passen.
Danksagung
Unser Team möchte sich bei Folgendem bedanken:
- @Dillicious möchte sich bei ihrem Partner und auch bei Low-Fi-Hip-Hop-Radio bedanken.
- @KimChiCook bedankt sich bei seinem 할머니
- @Piccalily möchte dem Chicago Handbuch of Style Online danken
- @GherKen möchte seinen drei Kindern dafür danken, dass sie all die Essiggurken gegessen haben, die er zubereiten kann.
- @VinegarViv möchte dem Rest des Teams dafür danken, dass er ihren Rücktritt berücksichtigt hat.
- @BBChips möchte sich bei Tunnock's Caramel Wafers bedanken.
- @GloriousPicklePat möchte der PickleDocs SIG für die Übernahme dieses Projekts danken
- Sam Scribe möchte der gesamten GloriousPickle-Community danken, insbesondere den Picklers, die ihnen während der Gläserknappheit im Sommer 2021 Gläser zum Einkochen schickten.