Aktuelle Phase:
Ergebnisse wurden bekannt gegeben. 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 2009) ist eine MIT-lizenzierte Bibliothek, mit der das perfekte Verhältnis von Salz, Zucker, Essig und Gewürzen für jedes Gemüse, das eingelegt werden kann, ganz einfach berechnet werden kann. Die Mengen reichen von einer einzelnen Minigurke bis hin zu Containerladungen Radieschen.
Autoren: Optional: Liste der Autoren der Fallstudie; bei Bedarf 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 fördern.
Projektbeschreibung
Angebot erstellen
Wie sind Sie auf die Idee für Ihren Google Season of Docs-Vorschlag gekommen? Welchen Prozess hat Ihre Organisation zur Entscheidungsfindung verwendet? Wie haben Sie Feedback eingeholt und berücksichtigt?
Die SIG GloriousPickle PickleDocs erfuhr über einen Tweet des Open-Source-Programs Office von Google vom Google Season of Docs-Programm. Die SIG besprach das Programm in ihrer zweiwöchentlichen Besprechung und stimmte zu, einen Vorschlag zu erstellen. Zwei Mitglieder der SIG (@KimChiCook und @Dillicious) haben sich freiwillig bereit erklärt, an dem Entwurf für den Vorschlag zu arbeiten, der im nächsten Meeting besprochen werden soll.
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 besprochen und eingearbeitet wurde, wurde der Vorschlag zur Abstimmung an das GloriousPickle Project Steering Committee 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 weniger ausgegeben als den Zuschussbetrag? Haben Sie die Mittel richtig zugewiesen oder waren einige der Positionen, für die Sie ein Budget festgelegt haben, zu hoch/niedrig/unnötig? Hatten Sie neben dem Google Season of Docs-Stipendium noch andere Mittel, die Sie nutzen konnten?
Zwei Mitglieder der GloriousPickle PickleDocs SIG haben als technische Redakteure gearbeitet (eine in Europa und eine 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 haben wir weniger T-Shirts an die Teilnehmer verschickt als geplant, sodass sich das ausgeglichen hat.
Außerdem haben wir uns entschieden, eine Mitwirkende von GloriousPickle, @Piccalily, zu bezahlen, die früher als professionelle Lektorin gearbeitet hat, damit sie die vom technischen Redakteur erstellte Dokumentation überarbeiten und Korrektur lesen kann.
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 (Lektorin)
- @GherKen, @VinegarViv (Admin-Hilfe, GPPSC)
- @BBChips, @GloriousPicklePat (Fachleute)
- Sam Scribe (Technical Writer)
Wir haben Sam Scribe über die Liste Google Season of Docs GitHub-Repository 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 Sam nur um wenige Stunden mit der der meisten Mitglieder der PickleDocs-SIG überschnitt, haben wir in unserem Diskussionsforum nach Picklern gesucht, 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 hat sich bereit erklärt, Fragen zu Verwaltung und Zahlung zu beantworten.
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 Mitglieder der PickleDocs-SIG haben sie vor jeder Besprechung geprüft und dafür gesorgt, 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 Google 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 des Monats haben wir einige Notizen aus einem früheren Versuch gefunden, die Dokumentation zu aktualisieren, der ins Stocken geraten war. Außerdem haben wir uns Teile der Materialien zur Reifeprüfung der Dokumentation im Google OpenDocs-Repository angesehen.
Nachdem wir die gute Nachricht erhalten hatten, dass wir für Google Season of Docs 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 Docs-Anwendung – Fall 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 |
| Entwurf für Anwendungsfall 2, geprüft von @GloriousPicklePat und @Dillicious | 9. Juli |
| Erster Entwurf des aktualisierten Anwendungsfalls für Google Docs 3 | 9. Juli |
| Entwurf für Anwendungsfall 3, geprüft von @Dillicious und @KimChiCook | 16. Juli |
| Alle Fragen 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 |
| Feedback aus Tests berücksichtigt | 10. September |
| Korrekturlesen und Korrekturlesen neuer Dokumente | 17. September |
| Der Entwurfsstatus von Google Docs wurde entfernt und Google Docs wurde 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:
So fügen Sie GloriousPickle eine neue Zutat hinzu
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 eine Anleitung zum Aktualisieren dieser Anleitungen für Nutzer in unser Projekt-Wiki aufgenommen.
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? Entsprachen die Messwerte den gewünschten Ergebnissen des Projekts? Haben sich Ihre Messwerte seit Ihrem Vorschlag geändert?
In unserem Vorschlag haben wir zwei Messwerte vorgeschlagen:
- Anzahl der inhaltsbezogenen Pull-Anfragen
- Anzahl der Pull-Requests von neuen Mitwirkenden
Im September (dem ersten vollen Monat nach der Veröffentlichung der Entwurfsdokumentation) haben wir einen Anstieg der inhaltsbezogenen Pull-Requests um 5% verzeichnet (von 20 im August auf 21 im September). Außerdem haben drei neue Mitwirkende insgesamt vier Pull-Requests gesendet (im August waren es zwei neue Mitwirkende mit zwei Pull-Requests). 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.
Uns ist zu Ohren gekommen, dass diese neue Dokumentation dazu beigetragen hat, dass neue Mitwirkende zur Zutatendatenbank von Glorious Pickle beitragen konnten. Ein neuer Mitwirkender erwähnte in seinem Beitrag, 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 Google 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 teilgenommen hat, indem sie Feedback zum ursprünglichen Vorschlag gegeben und die neuen Dokumente in Form von Entwürfen getestet hat.
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 verlassen hat. 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 diese 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 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: 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 freuen uns sehr, dass Sam das Einlegen für sich entdeckt hat und dass wir ihn in unserer Community „einfangen“ konnten.
Wir empfehlen anderen Projekten Folgendes:
- 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.) Wir hatten mehr als genug Arbeit, um Sam zu beschäftigen.
- Nutzen Sie Ihr Netzwerk, wenn Sie nach einem technischen Redakteur suchen. Bitte alle in deiner Community um Empfehlungen. Obwohl wir Sam über das GitHub-Konto von Google Season of Docs gefunden haben, waren wir zuversichtlich, mit ihm zusammenzuarbeiten, da wir während der Bewerbungsphase mit mehreren Personen gesprochen hatten.
- 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. Zuerst war Sam besorgt, wie viel Feedback er von der Community erhalten würde und wie er es einbinden könnte. Das Modell des „groben Konsenses“ unserer Community („Ein Konsens wird erreicht, wenn alle Probleme angesprochen, aber nicht unbedingt berücksichtigt werden“) gab Sam jedoch die Zuversicht, Kritik mithilfe seiner Fachkenntnisse im technischen Schreiben anzugehen.
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 können Sie auch Links zu den von Ihnen verwendeten Dokumentationstools oder ‑ressourcen auflisten oder Danksagungen oder Erwähnungen hinzufügen, die nicht in die oben genannten Abschnitte passen.
Danksagung
Unser Team möchte sich bei folgenden Personen und Institutionen bedanken:
- @Dillicious möchte ihrem Partner und 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 sich bei seinen drei Kindern bedanken, dass sie alle Gurken essen, die er machen kann.
- @VinegarViv möchte sich beim Rest des Teams für die Unterstützung bedanken.
- @BBChips bedankt sich bei dem besten nicht eingelegten Lebensmittel, das es gibt: Tunnock's Karamellwaffeln.
- @GloriousPicklePat möchte der PickleDocs-SIG für die Übernahme dieses Projekts danken.
- 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.