Aktuelle Phase:
Das Programm „Season of Docs“ 2021 endete am 14. Dezember 2021. Siehe Zeitachse.
Verwenden Sie dieses Beispiel, um Ihren eigenen Fallstudienbericht zu erstellen.
PicklePlus: Dokumentation des GloriousPickle-Beitragstools
Organisation oder Projekt: Glorious Pickle Link zur Hauptwebsite Ihrer Organisation oder Ihres Projekts hier
Beschreibung der Organisation: GloriousPickle (aktuelle Version 1.2.3, erste Veröffentlichung 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 jedes mögliche eingelegte Gemüse in Mengen, die von einer einzelnen Babygurke bis zu Behältern mit Rettichen reichen.
Autoren: optional: Die Autoren der Fallstudie auflisten; auf Anfrage Nutzernamen verwenden
Problembeschreibung/Zusammenfassung des Vorschlags
Welches Problem wollten Sie mit einer neuen oder verbesserten Dokumentation lösen? Verlinken Sie nach Möglichkeit die Seite mit dem Vorschlag auf Ihrer Projektwebsite.
Das Hinzufügen von Zutaten zur Zutatendatenbank des GloriousPickle-Tools ist zeitaufwendig und kompliziert. Außerdem ist das Tool nicht gut dokumentiert. Viele potenzielle Mitwirkende haben keine Erfahrung mit Git oder dem Erstellen von Pull-Requests. Das bedeutet, dass es bei GloriousPickle erhebliche Lücken in den Zutatendaten gibt, was unser Tool weniger nützlich macht. Durch die Verbesserung der Dokumentation für das Hinzufügen neuer Zutaten möchten wir neue Mitwirkende gewinnen und mehr Eintöpfe anregen.
Projektbeschreibung
Angebot erstellen
Wie sind Sie auf die Idee für Ihren Season of Docs-Vorschlag gekommen? Welchen Prozess hat Ihre Organisation zur Entscheidungsfindung verwendet? Wie haben Sie Feedback eingeholt und berücksichtigt?
Die PickleDocs SIG von GloriousPickle erfuhr über einen Tweet des Open Source Programs Office von Google vom Programm „Season of Docs“. Die SIG besprach das Programm in ihrer zweiwöchentlichen Besprechung und stimmte zu, einen Vorschlag zu erstellen. Zwei Mitglieder des SIG (@KimChiCook und @Dillicious) meldeten sich freiwillig, um beim nächsten Meeting an dem Entwurf zu arbeiten, der überprüft werden sollte.
Nachdem sich die PickleDocs-SIG auf den Entwurf des Vorschlags geeinigt hatte, wurde eine E-Mail an das gesamte Projekt gesendet, in der um Feedback gebeten wurde. Vierzehn Communitymitglieder haben Feedback gegeben, darunter @GloriousPicklePat, die Betreuerin der API zum Hinzufügen von Zutaten. @GloriousPicklePat hat sich freiwillig bereit erklärt, während des Programms als Ressource zur Verfügung zu stehen.
Nachdem das erhaltene Feedback diskutiert und berücksichtigt wurde, wurde der Vorschlag an das Lenkungskomitee des GloriousPickle-Projekts zur Abstimmung gesendet. Alle fünf Mitglieder des GPPSC haben für die Einreichung des Vorschlags und des Antrags gestimmt. Außerdem hat @VinegarViv zugestimmt, beim Erstellen des Open Collective-Kontos zu helfen, das für die Teilnahme am Programm und die Verwaltung der Zahlungen erforderlich ist.
Budget
Fügen Sie einen kurzen Abschnitt zu Ihrem Budget hinzu. Wie haben Sie die Arbeit geschätzt? Gab es unerwartete Kosten? Haben Sie am Ende weniger ausgegeben als die Fördergelder? Hatten Sie andere Mittel außerhalb von Season of Docs, die Sie nutzen konnten?
Zwei Mitglieder von GloriousPickle PickleDocs SIG haben als technische Redakteure gearbeitet (eines in Europa und eines in Argentinien). Sie halfen uns, die Arbeit zu schätzen und ähnliche Projektbudgets zu finden, indem sie den Entwurf des zuvor erstellten Angebots verglichen. Außerdem hatten wir noch 1.000$an uneingeschränkten Sponsorengeldern von unserer PicklePals-Convention 2019 übrig, die wir dem Projekt zugewiesen haben.
Eine unvorhergesehene Ausgabe war die Anmietung eines WLAN-Hotspots für unseren technischen Redakteur, da er sich in einem von Waldbränden betroffenen Gebiet befand und zu Hause keinen Internetzugang mehr hatte. Außerdem verschickten wir am Ende weniger T-Shirts an die Teilnehmer als geplant, sodass das Gleichgewicht lag.
Außerdem haben wir beschlossen, die Mitwirkenden von GloriousPickle, @Piccalily, die einst professionelle Texterin in ihrem Leben ohne Pickle war, für die Textbearbeitung und das Korrekturlesen der Dokumentation zu entschädigen.
Teilnehmer
Wer hat an diesem Projekt gearbeitet? Geben Sie bei Bedarf die Nutzernamen an. Wie haben Sie Ihren technischen Redakteur gefunden und eingestellt? Wie haben Sie andere freiwillige Helfer oder bezahlte Teilnehmer gefunden? Welche Rollen hatten sie? Hat jemand das Programm abgebrochen? Was haben Sie über Personalbeschaffung, Kommunikation und Projektmanagement gelernt?
Das Kernteam, das an diesem Projekt arbeitete, bestand aus:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (Kopierer)
- @GherKen, @VinegarViv (Administratorhilfe, GPPSC)
- @BBChips, @GloriousPicklePat (Fachleute)
- Sam Scribe (Technical Writer)
Wir haben Sam Scribe in der GitHub-Repository-Liste für Season of Docs gefunden. Wir dachten, dass seine Erfahrung (Sam hatte für ein Kochmagazin gearbeitet und Dokumentationen für Websites verfasst) gut zu unserem Projekt passte. Sam nahm am zweiwöchigen Anruf der PickleDocs-SIG teil und besprach das Projekt mit uns. Dabei machte er mehrere sehr wertvolle Vorschläge, die wir in den Vorschlag einbauten. Wir haben uns auch an zwei weitere technische Redakteure gewandt, die uns über die Netzwerke unserer SIG-Mitglieder bekannt waren, aber keiner von ihnen war während des Programmzeitraums verfügbar.
Da sich die Zeitzone von Samuel nur wenige Stunden mit den meisten Mitgliedern der PickleDocs SIG überschneidet, riefen wir in unserem Diskussionsforum einen Anruf an die Pickler an, die sich in Sams Zeitzone befanden und mit dem Hinzufügen von Zutaten vertraut waren. @BBChips bot an, Sams Fragen zu beantworten und ihm bei Bedarf bei der Suche nach anderen Experten zu helfen. @GloriousPicklePat bot sich auch an, Sam bei der zugrunde liegenden Architektur des Tools und möglichen Fehlermeldungen von der API zu helfen, und stellte Hilfe zu GitHub und git zur Verfügung.
Leider musste @VinegarViv aus persönlichen Gründen mitten im Programm aus dem Projekt aussteigen. Das GPPSC-Mitglied @GherKen kümmerte sich um Verwaltungs- und Zahlungsfragen.
Nachdem einige Fragen übersehen wurden (GloriousPickle verwendet eine kostenlose Slack-Instanz und gelegentlich verläuft die Diskussion so schnell, dass Unterhaltungen aufgrund des Limits für das rollierende Archiv verloren gehen), haben wir gelernt, dass wir eine Liste der laufenden Fragen in einem freigegebenen Dokument aufbewahren sollten. Wir haben ein freigegebenes Google-Dokument verwendet. Die SIG-Mitglieder von PickleDocs haben dies vor jeder Besprechung überprüft und sichergestellt, dass sie vor Ende der Besprechung Antworten erhalten. Sam konnte @BBChips bei dringenden Fragen direkt kontaktieren.
Wir haben die Zusammenarbeit mit Sam sehr genossen. Er hat nicht nur die Dokumentation für Glorious Pickle aktualisiert, sondern ist auch selbst zu einem begeisterten Einwecker geworden.
Zeitachse
Geben Sie einen kurzen Überblick über den Zeitplan Ihres Projekts. Geben Sie das geschätzte Enddatum oder Zwischenmeilensteine an, falls das Projekt noch läuft.
Während wir auf die Bekanntgabe der teilnehmenden Organisationen im Rahmen des Season of Docs-Programms warteten, suchten die Mitglieder der PickleDocs-SIG nach früheren Arbeiten, die für Sam nützlich sein könnten. Im Laufe eines Monats haben wir einige Notizen aus früheren Bemühungen zur Aktualisierung der angehaltenen Dokumentation gefunden. Außerdem haben wir Teile der Prüfungsmaterialien zur Dokumentationsreife im Opendocs-Repository von Google durchgearbeitet.
Nachdem wir die gute Nachricht erhalten hatten, dass wir für die Season of Docs 2021 ausgewählt wurden, haben Sam und die PickleDocs SIG einen groben Zeitplan aufgestellt:
| Phase | Abgeschlossen von |
|---|---|
| Überprüfung von Dokumenten | 7. Mai |
| 3 Anwendungsfälle für das Friction Log | 14. Mai |
| Probleme mit @GloriousPicklePat und @BBChips besprechen und Fragen beantworten | 28. Mai |
| Erster Entwurf der aktualisierten Dokumentation – Anwendungsfall 1 | 25. Juni |
| Entwurf für Anwendungsfall 1, geprüft von @GloriousPicklePat und @KimChiCook | 2. Juli |
| Erster Entwurf des aktualisierten Anwendungsfalls für Google Docs 2 | 2. Juli |
| Anwendungsfall 2: Entwurf geprüft von @GloriousPicklePat und @Dillicious | 9. Juli |
| Erster Entwurf des aktualisierten Anwendungsfalls für Google Docs 3 | 9. Juli |
| Anwendungsfall 3: Entwurf geprüft von @Dillicious und @KimChiCook | 16. Juli |
| Alle Anfragen zu allen Anwendungsfällen beantwortet | 30. Juli |
| Die meisten Mitglieder der PickleDocs-SIG waren vom 1. bis 20. August im Urlaub. | -- |
| Testen neuer Dokumente in der Community beginnen (als Entwürfe auf der GloriousPickle-Website veröffentlichte Dokumente) | 21. August |
| Testfeedback eingearbeitet | 10. September |
| Lektorieren und Korrekturlesen neuer Dokumente | 17. September |
| Entwurfsstatus von Dokumenten entfernt, Dokumente offiziell eingeführt | 28. September |
| Verfahren zum Aktualisieren der erstellten Dokumentation | 1. November |
| Diese Fallstudie wurde erstellt | 8. November |
| Fallstudie eingereicht | 16. November |
In unserem Angebotsbudget hatten wir geschätzt, dass der Technische Redakteur 10 bis 15 Stunden pro Woche an unserem Projekt arbeiten würde. Sam hat die aufgewendete Zeit aufgezeichnet und kam auf durchschnittlich 11,5 Stunden pro Woche.
Ergebnisse
Was wurde erstellt, aktualisiert oder anderweitig geändert? Fügen Sie gegebenenfalls Links zu veröffentlichter Dokumentation hinzu. Gab es im Angebot Arbeitsergebnisse, die nicht erstellt wurden? Geben Sie diese auch an.
Drei wichtige Anwendungsfälle wurden mit ausführlichen Anleitungen für Nutzer dokumentiert:
Eine neue Zutat zu GloriousPickle hinzufügen
GloriousPickle eine Variante hinzufügen
Zutat in GloriousPickle aktualisieren oder korrigieren
Diese Leitfäden enthielten auch neue Vorlagen für Pull-Anfragen, um Beiträge zu erleichtern.
Außerdem hat Sam während des Projekts ein kleines Pickle-Glossar mit Begriffen erstellt, die er gelernt hat. Dieses Glossar wurde auch auf der Projektwebsite von GloriousPickle veröffentlicht.
Wir haben unserem Projekt-Wiki Anweisungen zum Aktualisieren dieser Nutzeranleitungen hinzugefügt.
Wir hatten geplant, eine Cheatsheet für neue GitHub-Nutzer zu erstellen, die ihnen bei der Nutzung unserer Prozesse und Tools helfen sollte. Nachdem wir uns jedoch die verfügbaren Ressourcen angesehen hatten, konnten wir stattdessen die Cheatsheet eines anderen Projekts forken.
Messwerte
Welche Messwerte haben Sie ausgewählt, um den Erfolg des Projekts zu messen? Konnten Sie diese Messwerte erfassen? Haben die Messwerte gut oder schlecht mit den gewünschten Ergebnissen des Projekts korreliert? Haben sich Ihre Messwerte seit Ihrem Vorschlag geändert?
In unserem Vorschlag haben wir zwei Messwerte vorgeschlagen:
- Anzahl der zutatenbezogenen Pull-Anfragen
- Anzahl der Pull-Anfragen von neuen Beitragenden
Im September (den ersten vollen Monat seit der Veröffentlichung des Entwurfs der Dokumentation) konnten wir einen Anstieg der zutatenbezogenen Pull-Anfragen um 5% beobachten (von 20 im August auf 21 im September). Außerdem gab es drei neue Beitragende, die insgesamt vier Pull-Anfragen stellten (im Vergleich zwei neue Beitragende, die im August zwei Pull-Anfragen stellten). Wir planen, diese Messwerte monatlich zu erfassen.
Ab dem 1. Januar erfassen wir außerdem die Anzahl der Mitwirkenden, die insgesamt mehr als drei Beiträge geleistet haben. Diese werden vierteljährlich nach der Veröffentlichung der Dokumentation erfasst.
Anekdotisch gesehen glauben wir, dass diese neue Dokumentation dazu beigetragen hat, dass neue Mitwirkende zur Zutatendatenbank von GloriousPickle beitragen konnten. Ein neuer Mitwirkender erwähnte im Kommentar zu seiner PR, dass er es schon einmal versucht hatte, die Aktualisierung aber nicht abgeschlossen hatte, weil er den Prozess nicht verstanden hatte.
Analyse
Was hat gut funktioniert? Was war unerwartet? Welche Hürden oder Rückschläge haben Sie erlebt? Halten Sie Ihr Projekt für erfolgreich? Warum bzw. warum nicht? (Wenn es noch zu früh ist, um das zu beurteilen, erklären Sie, wann Sie den Erfolg Ihres Projekts voraussichtlich beurteilen können.)
Wir sind sehr zufrieden mit dem Ergebnis unseres Season of Docs-Projekts und betrachten es als Erfolg. Die neue Dokumentation ist klar und hilfreich. Wir haben bereits eine gewisse Steigerung der Anzahl der Pull-Requests zu Inhaltsstoffen und der Anzahl der Pull-Requests von neuen Mitwirkenden festgestellt.
Wir waren auch froh, dass fast die gesamte GloriousPickle-Community an der Umfrage teilnahm, indem wir Feedback zum ursprünglichen Vorschlag gegeben und die neuen Dokumente als Entwurf getestet haben.
Wir mussten einige unerwartete Hürden überwinden. Wir waren dankbar, dass die Waldbrände in Sams Bundesstaat nicht mehr Schaden angerichtet haben als einen Internetausfall. Außerdem bedauern wir, dass @VinegarViv das Projekt verlässt. Wir wünschen ihr und ihrer Familie alles Gute und hoffen, sie bald wiederzusehen.
Uns war nicht bewusst, wie viele Begriffe und Akronyme im Zusammenhang mit Pickles für jemanden, der neu in unserem Projekt ist, unbekannt sein würden, bis Sam mit der Arbeit an der Dokumentation begann. Sam machte sich jedoch die Mühe, eine Liste aller unbekannten Begriffe zu erstellen und sie durch eigene Recherchen und durch Nachfragen bei Communitymitgliedern zu definieren. Dieses Gurken-Glossar wird uns dabei helfen, in Zukunft mehr Menschen in die Gurken-Community aufzunehmen.
Zusammenfassung
Fassen Sie in 2 bis 4 Absätzen Ihre Projekterfahrung 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, bei denen versucht wird, ein ähnliches Problem mit der Dokumentation zu lösen?
Kurz gesagt: Es war einfach nur Gurkenmäßig! Wir haben die Dokumentationsleistungen erbracht und unsere Messwerte scheinen unseren Zielen zu entsprechen.
Ein großer Teil des Erfolgs dieses Projekts ist auf die Zusammenarbeit mit unserem technischen Redakteur Sam Scribe zurückzuführen. [Ich habe das nicht geschrieben – Sam] Obwohl Sam keine Erfahrung mit Picklen oder GitHub hatte, war er als erfahrener technischer Redakteur bereit, sich in ein neues Thema einzuarbeiten, Fragen zu stellen und Nachforschungen anzustellen. Sam hat sich schnell nicht nur unsere Projekttools zu eigen gemacht (wir verwenden ein Kanban-Board, um den Überblick über die Arbeit zu behalten), sondern auch unsere Gurkenwitze! Wir sind sehr froh, dass Sam den Essig-Feuchtling gefangen hat und sie in unserer Gemeinde abgefüllt haben.
Wir würden anderen Projekten Folgendes empfehlen:
- Halten Sie Ihre Vorschläge klein und überschaubar. (Ursprünglich wollten wir in unserem Vorschlag eine Dokumentation zur Verwendung unseres Estimators mit industriellen Einlegemaschinen für Chargen einschließen, haben sie aber nur ausgelassen, weil eines unserer Communitymitglieder, das sich intensiv mit der Open-Source-Nutzung von Einlegemaschinen befasst, während des Programms ihre Doktorarbeit schreiben wollte.) Am Ende hatten wir mehr als genug Arbeit, um Sam beschäftigt zu halten!
- Nutzen Sie Ihre Netzwerke, wenn Sie nach einem technischen Redakteur suchen. Bitte alle in deiner Community um Empfehlungen. Obwohl wir Sam über das GitHub-Video der Season of Docs gefunden haben, fühlten wir uns sicher, mit ihm zusammenzuarbeiten, da wir während der Bewerbungsphase mit mehreren Personen gesprochen haben.
- Willkommen in der Community! Sam hat uns mitgeteilt, dass es dank der enthusiastischen Haltung der GloriousPicklers ganz einfach war, Fragen zu stellen.
- Helfen Sie Ihren technischen Redakteuren, Open-Source-Kenntnisse zu erwerben. Sam hatte Git noch nie verwendet, aber nach ein paar Tutorials war er schnell auf dem neuesten Stand. Anfangs war er besorgt darüber, wie viel Feedback er von der Community erhalten könnte und wie er dieses umsetzen könnte. Aber dank des groben Konsensmodells („Konsens wird erreicht, wenn alle Probleme gelöst, aber nicht unbedingt berücksichtigt werden“) hat Sam überzeugt, dass er mit seinem technischen Know-how auf Kritik eingehen kann.
Anhang
Wenn Sie andere Materialien haben, auf die Sie verlinken möchten (z. B. einen Vertrag für die Zusammenarbeit mit Ihrem technischen Redakteur, den Sie teilen möchten, oder Vorlagen für Ihr Dokumentationsprojekt oder andere offene Dokumentationsressourcen), können Sie sie hier auflisten und verlinken. Im Anhang findest du außerdem Links zu Dokumentationstools oder Ressourcen, die du verwendet hast, sowie Orte, an denen du Danksagungen oder Danksagungen hinzufügen kannst, die nicht in die obigen Abschnitte passen.
Danksagung
Unser Team möchte sich bei folgenden Personen und Institutionen bedanken:
- @Dillicious möchte ihrem Partner und dem Low-Fi-Hip-Hop-Radio danken.
- @KimChiCook möchte seiner 할머니 danken, dass sie ihm das Einlegen beigebracht hat.
- @Piccalily möchte dem Chicago Manual of Style Online danken.
- @GherKen möchte seinen drei Kindern dafür danken, dass sie so viele Essiggurken gegessen haben
- @VinegarViv möchte sich beim Rest des Teams für ihren Rückzug bedanken
- @BBChips möchte sich für das beste nicht eingelegte Essen bedanken, Tunnock's Caramel Wafers
- @GloriousPicklePat möchte sich bei den PickleDocs SIG für die Übernahme dieses Projekts bedanken.
- Sam Scribe möchte sich bei der gesamten GloriousPickle-Community bedanken, vor allem aber bei den Picklern, die ihm während der Gläserknappheit im Sommer 2021 Einmachgläser geschickt haben und ihn so auf den Weg zu vielen leckeren Gurken gebracht haben.