Mevcut aşama:
2021 Belge Sezonu programı 14 Aralık 2021'de sona erdi. Zaman çizelgesine bakın.
Kendi vaka çalışması raporunuzu oluşturmak için bu örneği kullanın.
PicklePlus: GloriousPickle Katkı Aracı'nı Belgeleme
Kuruluş veya Proje: Glorious Pickle kuruluşunuzun veya projenizin ana sitesine bağlantıyı buraya ekleyin
Kuruluş Açıklaması: GloriousPickle (mevcut sürüm 1.2.3, ilk sürüm 2009'da), tek bir küçük salatalıktan konteyner gemisi dolusu turpa kadar her türlü turşu yapılabilir sebze için tuz, şeker, sirke ve baharatların mükemmel oranını kolayca hesaplayan MIT lisanslı bir kitaplıktır.
Yazarlar: isteğe bağlı: Örnek olayın yazarlarını listeleyin; istenen durumlarda kullanıcı adlarını kullanın
Sorun Açıklaması/Öneri Özeti
Yeni veya iyileştirilmiş dokümanlarla çözmeye çalıştığınız sorun neydi? Mümkünse proje sitenizdeki teklif sayfasının bağlantısı
GloriousPickle aracının içerik veritabanına içerik eklemek zaman alıcı ve karmaşıktır. Ayrıca araçta iyi dokümanlar yoktur. Katkıda bulunmak isteyenlerin çoğu git kullanma veya çekme isteği gönderme konusunda deneyimli değildir. Bu, GloriousPickle'ın içerik verilerimizde ciddi boşluklar olduğu anlamına gelir ve aracımızı daha az kullanışlı hale getirir. Yeni içerik eklemeyle ilgili dokümanları iyileştirerek yeni katkıda bulunanları ve turşu severleri teşvik etmeyi umuyoruz.
Proje açıklaması
Teklif oluşturma
Belgesel Sezonu önerinizi nasıl oluşturdunuz? Kuruluşunuz bir fikre karar vermek için hangi süreci kullandı? Geri bildirimi nasıl istediniz ve nasıl dahil ettiniz?
GloriousPickle PickleDocs SIG, Dokümanlar Sezonu programından Google'ın Açık Kaynak Programlar Ofisi'nin bir tweet'i aracılığıyla haberdar oldu. SIG, iki haftada bir yapılan toplantıda programı tartıştı ve bir teklif oluşturmaya karar verdi. SIG'deki iki üye (@KimChiCook ve @Dillicious), bir sonraki toplantıda incelenmek üzere taslak teklif üzerinde çalışmaya gönüllü oldu.
PickleDocs SIG, teklif taslağı üzerinde anlaştıktan sonra daha geniş kapsamlı projeye geri bildirim isteğinde bulunan bir e-posta gönderildi. İçerik ekleme API'sinin geliştiricisi @GloriousPicklePat da dahil olmak üzere on dört topluluk üyesi geri bildirimde bulundu. @GloriousPicklePat program sırasında kaynak olarak gönüllü oldu.
Alınan geri bildirimler tartışılıp projeye dahil edildikten sonra teklif, oylama için GloriousPickle Proje Yönlendirme Komitesi'ne gönderildi. GPPSC'nin beş üyesi de önerinin ve başvurunun gönderilmesi için +1 oy kullandı. @VinegarViv de programa katılmak ve ödemeleri denetlemek için gereken Open Collective hesabının oluşturulmasına yardımcı olmayı kabul etti.
Bütçe
Bütçenizle ilgili kısa bir bölüm ekleyin. Çalışmayı nasıl tahmin ettiniz? Beklenmedik masraflar var mıydı? Hibe ödülünden daha az harcama yaptınız mı? Belge Sezonu dışında kullanabileceğiniz başka kaynaklarınız var mıydı?
GloriousPickle PickleDocs SIG'in iki üyesi teknik yazar olarak çalışmıştır (biri Avrupa'da, diğeri Arjantin'de). Daha önce hazırladıkları taslak teklif çalışmalarını karşılaştırarak çalışmayı tahmin etmemize ve benzer proje bütçeleri bulmamıza yardımcı oldular. Ayrıca, 2019 PicklePals kongresimizden kalan ve projeye ayırdığımız 1.000 ABD doları tutarında sponsorluk paramız da vardı.
Teknik yazarımız, orman yangınlarından etkilenen bir bölgede olduğu ve evinde internet erişimini kaybettiği için beklenmedik bir harcama yaparak kablosuz hotspot kiraladı. Ayrıca katılımcılara planladığımızdan daha az tişört gönderdik.
Ayrıca, teknik yazar tarafından oluşturulan dokümanların düzeltme ve gözden geçirme işlemlerine yardımcı olması için GloriousPickle'a katkıda bulunan @Piccalily'ye (bir zamanlar turşu dışındaki hayatında profesyonel bir düzeltmen olan) ödeme yapmaya karar verdik.
Katılımcı sayısı
Bu projede kimler çalıştı (Katılımcılar tarafından istenirse kullanıcı adlarını kullanın)? Teknik yazarınızı nasıl bulup işe aldınız? Diğer gönüllüleri veya ücretli katılımcıları nasıl buldunuz? Hangi rolleri üstlendiler? Ayrılan oldu mu? İşe alma, iletişim ve proje yönetimi hakkında neler öğrendiniz?
Bu projede çalışan çekirdek ekip:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (copyeditor)
- @GherKen, @VinegarViv (yönetici yardımı, GPPSC)
- @BBChips, @GloriousPicklePat (konunun uzmanları)
- Sam Scribe (teknik yazar)
Sam Scribe'i Season of Docs GitHub deposu listesinden bulduk. Sam'in deneyiminin (Sam bir yemek dergisi için çalışmış ve web siteleri için doküman yazmıştı) projemizle iyi bir uyum içinde olduğunu düşündük. Sam, PickleDocs SIG'nin iki haftada bir yapılan görüşmesine katıldı ve proje hakkında bizimle konuştu. Teklife dahil ettiğimiz çok değerli önerilerde bulundu. Ayrıca, SIG üyelerimizin ağları aracılığıyla tanıdığımız iki teknik yazarla da iletişime geçtik ancak ikisi de program süresi boyunca müsait değildi.
Sam'in saat dilimi, PickleDocs SIG üyelerinin çoğuyla yalnızca birkaç saat çakıştığından, tartışma forumumuzda Sam'in saat diliminde olan ve içerik ekleme sürecine aşina olan turşu üreticilerine bir çağrı gönderdik. @BBChips, Sam'in sorularını yanıtlamak ve gerektiğinde başka uzmanlar bulmasına yardımcı olmak için gönüllü oldu. @GloriousPicklePat, Sam'in aracın temel mimarisini ve API'den gelen olası hata mesajlarını anlamasına yardımcı olmak için gönüllü oldu ve GitHub ile git konusunda yardım sağladı.
Maalesef @VinegarViv, programın ortasında kişisel nedenlerle projeden ayrılmak zorunda kaldı. GPPSC üyesi @GherKen, idari ve ödemeyle ilgili soruları yanıtlamak için devreye girdi.
Bazı soruları kaçırdıktan sonra (GloriousPickle ücretsiz bir Slack örneği kullanıyor ve bazen tartışma o kadar hızlı ilerliyor ki, arşivleme sınırı nedeniyle sohbetleri kaybediyoruz) devam eden soruların listesini paylaşılan bir dokümanda tutmamız gerektiğini öğrendik (paylaşılan bir Google Dokümanı kullandık). PickleDocs SIG üyeleri her toplantıdan önce bu sayfayı kontrol etti ve toplantı sona ermeden önce yanıt almalarını sağladı. Sam, acil sorular için @BBChips hesabını doğrudan pingleyebiliyordu.
Sam ile çalışmaktan çok memnun kaldık. Sam, GloriousPickle dokümanlarını güncellemenin yanı sıra kendisi de hevesli bir turşu üreticisi oldu.
Zaman çizelgesi
Projenizin zaman çizelgesine kısaca göz atın (proje devam ediyorsa tahmini bitiş tarihini veya ara hedefleri belirtin).
Belge Sezonu programının katılımcı kuruluşlarını açıklamasını beklerken PickleDocs SIG üyeleri, Sam'in işine yarayacağını düşündüğümüz önceki çalışmaları aradı. Bir ay boyunca, dokümanları güncellemeyle ilgili daha önce başlatılan ancak yarıda bırakılan bir çalışmadan bazı notlar bulduk ve Google opendocs repo'sundaki doküman olgunluk denetimi materyallerinin bazı bölümlerinde de çalıştık.
2021 Dokümanlar Sezonu'na seçildiğimiz müjdesini aldıktan sonra Sam ve PickleDocs SIG bir araya gelerek kaba bir program hazırladı:
| Aşama | Tamamlayan |
|---|---|
| Belge denetimini inceleme | 7 Mayıs |
| Sorun günlüğü 3 kullanım alanı | 14 Mayıs |
| @GloriousPicklePat ve @BBChips ile sürtünme günlüklerini inceleyin, sorguları yanıtlayın | 28 Mayıs |
| Güncellenen dokümanlar kullanım alanı 1'in ilk taslağı | 25 Haziran |
| @GloriousPicklePat ve @KimChiCook tarafından incelenen 1. kullanım alanı taslağı | 2 Temmuz |
| Güncellenen dokümanlar kullanım alanı 2'nin ilk taslağı | 2 Temmuz |
| @GloriousPicklePat ve @Dillicious tarafından incelenen 2. kullanım alanı taslağı | 9 Temmuz |
| Güncellenen dokümanlar kullanım alanı 3'ün ilk taslağı | 9 Temmuz |
| @Dillicious ve @KimChiCook tarafından incelenen 3. kullanım alanı taslağı | 16 Temmuz |
| Tüm kullanım alanlarında tüm sorgular yanıtlandı | 30 Temmuz |
| PickleDocs SIG'nin çoğu 1-20 Ağustos tarihleri arasında tatildeydi | -- |
| Toplulukta yeni dokümanların testine başlama (GloriousPickle sitesinde taslak olarak yayınlanan dokümanlar) | 21 Ağustos |
| Test geri bildirimleri dahil edildi | 10 Eylül |
| Yeni dokümanların düzeltilmesi ve gözden geçirilmesi | 17 Eylül |
| Dokümanların taslak durumu kaldırıldı, dokümanlar resmi olarak kullanıma sunuldu | 28 Eylül |
| Dokümanları güncelleme süreci oluşturuldu | 1 Kasım |
| Bu vaka çalışması oluşturuldu | 8 Kasım |
| Örnek olay gönderildi | 16 Kasım |
Teklif bütçemizde, teknik yazarın projemiz üzerinde haftada 10-15 saat çalışacağını tahmin etmiştik. Sam, harcadığı süreyi kaydetti ve haftada ortalama 11,5 saat harcadığını tespit etti.
Sonuçlar
Neler oluşturuldu, güncellendi veya başka şekilde değiştirildi? Varsa yayınlanmış dokümanların bağlantılarını ekleyin. Teklifteki oluşturulmayan teslimatlar var mıydı? Bunları da listeleyin.
Üç önemli kullanım alanı, kullanıcılara yönelik tam kullanım kılavuzlarıyla belgelendi:
GloriousPickle'a yeni bir malzeme ekleme
GloriousPickle'a varyant bir bileşen ekleme
GloriousPickle'daki bir malzemeyi güncelleme veya düzeltme
Bu kılavuzlarda, katkıları kolaylaştırmak için yeni çekme isteği şablonları da yer aldı.
Ayrıca Sam, proje sırasında öğrendiği terimlerin yer aldığı küçük bir turşu sözlüğü oluşturdu ve bu sözlüğü GloriousPickle proje sitesinde yayınladı.
Bu kullanıcı kılavuzlarını güncellemeyle ilgili talimatları proje wiki'mize ekledik.
GitHub'da yeni olan katkıda bulunanların süreçlerimizi ve araçlarımızı kullanmalarına yardımcı olmak için bir alıştırma sayfası oluşturmayı planlamıştık. Ancak mevcut kaynaklara göz attığımızda bunun yerine başka bir projenin alıştırma sayfasını çatallayabildik.
Metrikler
Projenin başarısını ölçmek için hangi metrikleri seçtiniz? Bu metrikleri toplayabildiniz mi? Metrikler, proje için istediğiniz sonuçlarla iyi mi yoksa kötü mü ilişkiliydi? Teklifinizden bu yana metrikleriniz değişti mi?
Teklifimizde iki metrik önerdik:
- bileşenle ilgili çekme isteklerinin sayısı
- yeni katkıda bulunanlardan gelen çekme isteklerinin sayısı
Eylül ayında (taslak dokümanların yayınlanmasından sonraki ilk tam ay), bileşenlerle ilgili çekme isteklerinde% 5 artış (Ağustos'ta 20, Eylül'de 21) ve toplam dört çekme isteği gönderen üç yeni katkıda bulunan (Ağustos'ta iki çekme isteği gönderen iki yeni katkıda bulunan) gördük. Bu metrikleri aylık olarak izlemeyi planlıyoruz.
1 Ocak'tan itibaren, dokümanlar yayınlandıktan sonra üçten fazla katkıda bulunanların sayısını da üç ayda bir takip edeceğiz.
Bu yeni dokümanların, yeni katkıda bulunanların GloriousPickle içerik veritabanına ekleme yapmalarını sağlama konusunda fark yarattığına inanıyoruz. Yeni bir katkıda bulunan, PR yorumunda daha önce denediğini ancak süreci anlamadığı için güncellemesini tamamlayamadığını belirtmişti.
Analiz
Neler iyi gitti? Beklemediğiniz bir durum oldu mu? Karşılaştığınız engeller veya aksilikler nelerdi? Projenizi başarılı buluyor musunuz? Neden evet veya neden hayır? (Henüz net bir fikir edinemediyseniz projenizin başarısını ne zaman değerlendirebileceğinizi açıklayın.)
Belgeler Sezonu projemizin sonucundan çok memnunuz ve projeyi başarılı buluyoruz. Yeni dokümanlar net ve faydalı. İçerikle ilgili çekme isteklerinin ve yeni katkıda bulunanların çekme isteklerinin sayısında artış olduğunu fark ettik.
Ayrıca, GloriousPickle topluluğunun neredeyse tamamının orijinal teklifle ilgili geri bildirim vererek ve yeni dokümanları taslak halinde test ederek bu sürece katılması bizi mutlu etti.
Beklemediğimiz birkaç engelle karşılaştık. Sam'in eyaletindeki orman yangınlarının internet kesintisi dışında başka bir hasara yol açmadığına sevindik. Ayrıca @VinegarViv'in projeden ayrılmasına üzüldük. Kendisine ve ailesine iyi günler diliyoruz. Yakında tekrar görüşmek dileğiyle.
Sam dokümanlar üzerinde çalışmaya başlayana kadar, projemize turşu hazırlama konusunda bilgi sahibi olmayan birinin turşu hazırlamayla ilgili terim ve kısaltmaların çoğunu bilmeyeceğinin farkında değildik. Ancak Sam, bilmediği her terimin listesini tutmaya özen gösterdi ve bu terimleri kendi araştırmaları ve topluluk üyelerinden açıklama ve referans isteyerek tanımladı. Bu Turşu Terimleri Sözlüğü, gelecekte turşu topluluğuna daha fazla kişi çekme konusunda büyük bir yardımcı olacaktır.
Özet
Proje deneyiminizi 2-4 paragrafta özetleyin. Neleri öğrendiğinizi ve gelecekte neleri farklı yapmayı tercih edeceğinizi vurgulayın. Belgelerle ilgili benzer bir sorunu çözmeye çalışan diğer projelere ne gibi tavsiyeler verirsiniz?
Kısacası, deneyimimiz pickletastic'ti. Doküman teslimatlarımızı tamamladık ve metriklerimiz hedeflerimize uygun görünüyor.
Bu projenin başarısının büyük bir kısmı, teknik yazarımız Sam Scribe ile çalışma şansına sahip olmamızdan kaynaklanıyor. [Bunu ben yazmadım. Sam] Sam, turşu kurma konusunda bilgili veya GitHub'da deneyimli olmasa da deneyimli bir teknik yazar olarak yeni bir konu alanına atılma, soru sorma ve araştırma yapma konusunda rahattı. Sam, hem proje araçlarımızı (işleri takip etmek için kanban panosu kullanırız) hem de turşu şakalarımızı hızla öğrendi. Sam'in turşu yapma hevesine kapıldığı ve turşularını topluluğumuzda paylaştığı için çok mutluyuz.
Diğer projelere önerimiz:
- Tekliflerinizi küçük ve yönetilebilir tutun. (Tahmin aracımızı endüstriyel toplu turşu makineleriyle kullanmayla ilgili dokümanları teklifimize dahil etmek istiyorduk. Ancak bu dokümanları yalnızca turşu makinelerini açık kaynak olarak geliştirmeye yoğun şekilde katılan topluluk üyelerimizden biri program sırasında doktora tezini yazacağı için dahil etmedik.) Sam'i meşgul edecek yeterince işimiz oldu.
- Teknik yazar ararken ağlarınızdan yararlanın. Topluluğunuzdaki herkesten öneri isteyin. Sam'i Dokümanlar Sezonu GitHub üzerinden bulsak da başvuru döneminde birçok kişiyle konuştuğumuz için onunla çalışmaktan emindik.
- Teknik yazarınıza topluluğunuzda hoş geldiniz deyin. Sam, GloriousPicklers'ın hevesli tavrının soru sormayı kolaylaştırdığını belirtti.
- Teknik yazarınızın açık kaynak becerilerini geliştirmesine yardımcı olun. Sam daha önce git kullanmamıştı ancak birkaç eğitimden sonra hızla konuyu öğrendi. Sam ilk başta topluluktan ne kadar geri bildirim alabileceği ve bu geri bildirimleri nasıl kullanacağı konusunda endişeliydi. Ancak topluluğumuzun "kabataslak fikir birliği" modeli ("fikir birliği, tüm sorunlar ele alındığında ancak mutlaka karşılanmadığında elde edilir") Sam'in teknik yazma uzmanlığını kullanarak eleştirileri ele almasına olanak tanıdı.
Ek
Bağlantı vermek istediğiniz başka materyalleriniz varsa (ör. teknik yazarınızla çalışmak için oluşturduğunuz ve paylaşmak istediğiniz bir sözleşme, doküman projeniz için şablonlar veya diğer açık doküman kaynakları) bunları burada listeleyebilir ve bağlayabilirsiniz. Ek, kullandığınız doküman araçlarının veya kaynakların bağlantılarını listelemenin ya da yukarıdaki bölümlere sığmayacak teşekkür veya teşekkür notları eklemenin de iyi bir yoludur.
Tasdik
Ekibimiz aşağıdaki kişileri ve konuları belirtmek istiyor:
- @Dillicious, eşine ve low-fi hip hop radyosuna teşekkür eder.
- @KimChiCook, turşu yapmayı öğrettiği için 할머니'ye teşekkür eder.
- @Piccalily, Chicago Stil Kılavuzu'na teşekkür eder.
- @GherKen, yaptığı tüm turşuları yedikleri için üç çocuğuna teşekkür ediyor
- @VinegarViv, görevinden ayrılmasına anlayış gösteren ekip üyelerine teşekkür etmek istiyor
- @BBChips, turşu dışındaki en iyi yiyecek olan Tunnock's Karamel Bisküvileri'ne teşekkür eder.
- @GloriousPicklePat, bu projeyi üstlendiği için PickleDocs SIG'ye teşekkür etmek istiyor
- Sam Scribe, GloriousPickle topluluğunun tamamına, özellikle de 2021 yazındaki kavanoz sıkıntısı sırasında kavanoz göndererek lezzetli turşuların yolunu açan turşu severlere teşekkür etmek istiyor.