Mevcut aşama:
2021 Dokümanlar Sezonu programı 14 Aralık 2021'de sona erdi. Zaman çizelgesini inceleyin.
Kendi örnek olay raporunuzu oluşturmanıza yardımcı olması için bu örnekten yararlanın.
PicklePlus: Glorious Pickle Katkı Aracını Belgeleme
Kuruluş veya Proje: Glorious Pickle'ın kuruluşunuzun veya projenizin ana sitesinin bağlantısını burada
Kuruluş Açıklaması: Glorious Pickle (geçerli sürüm 1.2.3, ilk sürümü 2009'da yayınlandı), tek bir bebek salatasından tek bir bebek salatasından saksılara turp konteynerine kadar çeşitli oranlarda mümkün olan her potansiyel turşu 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. İstenirse kullanıcı adlarını kullanın.
Sorun Bildirimi/Teklif Özeti
Yeni veya iyileştirilmiş belgelerle hangi sorunu çözmeye çalışıyordunuz? Mümkünse proje sitenizdeki teklif sayfasının bağlantısını verin.
Glorious Pickle aracının malzeme veritabanına bileşen eklemek zaman alıcı ve karmaşık bir işlemdir ve araç iyi dokümanlara sahip değildir. Katkıda bulunan birçok kullanıcının git kullanımı veya pull isteği oluşturma deneyimi yoktur. Bu, Glorious Pickle'ın malzeme verilerimizde ciddi boşluklar olduğu ve aracımızı daha az kullanışlı hale getirdiği anlamına geliyor. Yeni malzemeler eklemeyle ilgili dokümanları geliştirerek yeni katılımcıları teşvik etmeyi ve daha fazla turşu çekmeyi amaçlamayı umuyoruz.
Proje Açıklaması
Teklif oluşturma
Dokümanlar Sezonu teklifinizi nasıl oluşturdunuz? Kuruluşunuz bir fikre karar verirken hangi süreci kullandı? Nasıl geri bildirim aldınız ve bu geri bildirimleri nasıl hayata geçirdiniz?
Glorious Pickle PickleDocs SIG, Google'ın Açık Kaynak Programlar Ofisi'nden gelen bir tweet'le, Dokümanlar Sezonu programını duyurdu. SIG, iki haftada bir düzenlenen toplantısında programı tartışmış ve bir teklif oluşturmayı kabul etmiştir. SIG'nin iki üyesi (@KimChiCook ve @Dillicious), bir sonraki toplantıda incelenmek üzere taslak öneri üzerinde çalışmaya gönüllü oldu.
PickleDokümanlar SIG teklif taslağı üzerinde anlaştıktan sonra, daha kapsamlı proje ekibine geri bildirim isteyen bir e-posta gönderildi. Malzeme ekleme API'sinin koruyucusu @Glorious PicklePat'in de aralarında bulunduğu on dört topluluk üyesi geri bildirimde bulundu. @Glorious PicklePat program boyunca kaynak olmaya gönüllü oldu.
Alınan geri bildirimleri tartışıp uygulamaya geçirdikten sonra, teklif, oylamak üzere Glorious Pickle Proje Yönlendirme Komitesi'ne gönderildi. GPPSC'nin beş üyesi de teklifin ve başvurunun gönderilmesi konusunda +1 oyu vermiştir ve @VinegarViv, programa katılmak ve ödemeleri denetlemek için gereken Open Collective hesabının oluşturulmasına yardımcı olmayı kabul etmiştir.
Bütçe
Bütçenize kısa bir bölüm ekleyin. İşi nasıl tahmin ettiniz? Beklenmedik giderler oldu mu? Sonuç olarak, bağış ödülünden daha az harcama yaptınız mı? Dokümanlar Sezonu dışında kullanabileceğiniz başka paranız var mıydı?
Glorious Pickle Pickle Docs SIG'nin iki üyesi, biri Avrupa'da, diğeri Arjantin'de olmak üzere teknik yazar olarak çalışmıştır. Bu kişiler, daha önce yaptıkları teklif taslağı çalışmasını karşılaştırarak işi tahmin etmemize ve benzer proje bütçelerini bulmamıza yardımcı oldu. Ayrıca, 2019 PicklePals kongresinden projeye ayırdığımız 1.000 ABD doları değerinde sınırsız sponsorluk parası kalmıştı.
Teknik yazarımız, orman yangınlarından etkilenen ve evindeki internet bağlantısının kesildiği bir bölgede olduğu için kablosuz hotspot kiralamasına yardımcı olmak, öngörülemeyen bir harcama sonucunda ortaya çıktı. Ayrıca katılımcılara planladığımızdan daha az tişört göndermeyi başardık ve bu nedenle dengeyi koruduk.
Ayrıca, teknik yazar tarafından oluşturulan belgelerin metin düzenleme ve gözden geçirme işlemlerine yardımcı olması için Glorious Pickle'a katkıda bulunan @Piccalily'ye (bir zamanlar sıra dışı hayatında profesyonel metin editörü olan) ödeme yapmaya karar verdik.
Katılımcı sayısı
Bu projede kimler çalışmış (katılımcılar tarafından istenirse kullanıcı adları 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? Ne gibi roller üstlendiler? Ayrılan oldu mu? İşe alım, iletişim ve proje yönetimi hakkında neler öğrendiniz?
Bu proje üzerinde çalışan çekirdek ekip:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (kopya düzenleyici)
- @GherKen, @VinegarViv (yönetici yardımı, GPPSC)
- @BBChips, @Glorious PicklePat (konuyla alakalı uzmanlar)
- Sam Scribe (teknik yazar)
Sam Scribe'i Season of Docs GitHub repository (Dokümanlar Sezonu GitHub deposu) listesinde bulduk. Bu kişilerin deneyimlerinin (Sam bir aşçılık dergisinde çalışmış ve web siteleri için dokümanlar hazırlamış) projemizle uyumlu olduğunu düşündük. Sam, iki haftada bir yapılan PickleDocs SIG telefon görüşmesine katıldı ve bizimle proje hakkında konuştu ve teklife dahil ettiğimiz çok değerli önerilerde bulundu. SIG üyelerinin ağları üzerinden tanıdığımız iki teknik yazara da ulaştık, ancak bu yazarların ikisi de programın süresi boyunca müsait değildi.
Cem'in saat dilimi PickleDokümanlar SIG'nin çoğu üyesinin çoğuyla yalnızca birkaç saat çakıştığından, tartışma forumumuzda, Sam'in saat diliminde olan ve malzeme ekleme işlemini bilen Seçiciler için bir arama gönderdik. @BBChips, Sam'in sorularını yanıtlamak ve gerektiğinde başka uzmanlar bulmalarına yardımcı olmak için gönüllü oldu. @Glorious PicklePat, Sam'in aracın temel mimarisini ve API'den gelecek olası hata mesajlarını anlamasına yardımcı olmak için gönüllü olarak GitHub ve Git yardımı sağladı.
Ne yazık ki programın ortasında @VinegarViv kişisel nedenlerle projeden uzaklaşmak zorunda kaldı. GPPSC üyesi @GherKen, idari ve ödemelerle ilgili sorularını yanıtlamak için harekete geçti.
Kaçırılan bazı sorulardan (Glorious Pickle ücretsiz bir Slack örneği kullanıyor ve bazen tartışmalar o kadar hızlı ilerliyor ki, aniden artan arşiv sınırı nedeniyle sohbetlerimizi kaybediyoruz), devam eden soruların bir listesini paylaşılan bir dokümanda saklamamız gerektiğini öğrendik (paylaşılan bir Google Dokümanı kullandık). PickleDokümanlar SIG üyeleri her toplantıdan önce bunu kontrol etmiş ve toplantı bitmeden önce sorularına cevap aldıklarından emin olmuştu. Cem, acil sorular için @BBChips adresine doğrudan ping atabildi.
Sam ve Sam ile çalışmaktan çok memnunuz. Glorious Pickle belgelerini güncellemenin yanı sıra kendisi de hevesli bir turist haline geldi!
Zaman çizelgesi
Projenizin zaman çizelgesiyle ilgili kısa bir özet verin (proje devam ediyorsa tahmini bitiş tarihini veya ara hedefleri belirtin).
Dokümanlar Sezonu programının katılan kuruluşları duyurmasını beklerken PickleDocs SIG üyeleri, Sam'in işine yarayacağını düşündüğümüz eski çalışmaları için bir arama yaptı. Bir ay boyunca, yarım kalmış dokümanları güncellemeye yönelik daha önceki bir çalışmada bazı notlar aldık. Ayrıca, Google opendocs deposundaki doküman olgunluğu denetimi malzemelerinin bazı bölümleri üzerinde çalıştık.
Güzel haberi aldıktan sonra, 2021 Dokümanlar Sezonu için seçildiğimizi bildiren Sam ile PickleDokümanlar SIG'i kabaca bir program üzerinde anladık:
| Aşama | Tamamlayan: |
|---|---|
| Doküman denetimini inceleyin | 7 Mayıs |
| Sorun günlüğü 3 kullanım alanları | 14 Mayıs |
| @Glorious PicklePat ve @BBChips ile sorun günlüklerini inceleme, sorguları yanıtlama | 28 Mayıs |
| Güncellenen dokümanların ilk taslağı kullanım alanı 1 | 25 Haziran |
| Kullanım alanı 1 taslağı @Glorious PicklePat ve @KimChiCook tarafından incelendi | 2 Temmuz |
| Güncellenen dokümanların ilk taslağı kullanım alanı 2 | 2 Temmuz |
| Kullanım alanı 2 taslağı | 9 Temmuz |
| Güncellenen dokümanların ilk taslağı kullanım alanı 3 | 9 Temmuz |
| Kullanım alanı 3 taslağı @Dillicious ve @KimChiCook tarafından incelendi | 16 Temmuz |
| Tüm kullanım alanlarında yanıtlanan tüm sorgular | 30 Temmuz |
| PickleDocs SIG'in çoğu 1-20 Ağustos tarihleri arasında tatildeydi | -- |
| Topluluktaki yeni dokümanları test etmeye başlayın (dokümanlar Glorious Pickle sitesinde taslak olarak yayınlandı) | 21 Ağustos |
| Test geri bildirimleri dahil edildi | 10 Eylül |
| Yeni dokümanları kopyalama ve gözden geçirme | 17 Eylül |
| Dokümanların taslak durumu kaldırıldı, dokümanlar resmi olarak kullanıma sunuldu | 28 Eylül |
| Oluşturulan dokümanları güncelleme işlemi | 1 Kasım |
| Bu örnek olay oluşturuldu | 8 Kasım |
| Örnek olay gönderildi | 16 Kasım |
Teklif bütçemizde teknik yazarın projemiz üzerinde çalışarak haftada 10-15 saat harcayacağını tahmin ediyorduk. Sam, harcanan süreyi kayıt altına aldı ve haftada ortalama 11,5 saat yaptı.
Sonuçlar
Neler oluşturuldu, güncellendi veya başka bir şekilde değiştirildi? Varsa yayınlanan belgelerin bağlantılarını ekleyin. Teklifte oluşturulmayan teslimatlar var mıydı? Bunları da listeleyin.
Üç temel kullanım alanı, eksiksiz kullanıcı "nasıl yapılır" kılavuzlarıyla belgelendi:
Glorious Pickle'a yeni bir malzeme ekleme
Glorious Pickle'a varyant malzeme ekleme
Glorious Pickle'taki bir malzeme nasıl güncellenir veya düzeltilir?
Bu kılavuzlar, katkıları kolaylaştırmak için yeni pull isteği şablonları da içeriyordu.
Ayrıca proje sırasında Sam, öğrendikleri terimlerin yer aldığı küçük bir Pickle Sözlüğü hazırladı ve bu sözlük de Glorious Pickle proje sitesinde yayınlandı.
Bu kullanıcı "Nasıl Yapılır?" kılavuzlarını güncellemek için gereken talimatları proje wiki'mize ekledik.
GitHub'a yeni katılanlar için süreçlerimizi ve araçlarımızı kullanmalarına yardımcı olacak kısa notlar oluşturmayı da eklemiştik, ancak mevcut kaynaklara göz attıktan sonra bunun yerine başka bir projenin yardımcı kısa bilgilerini eklemeyi başardık.
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 veya kötü örtüştü mü? Teklifinizden bu yana metrikleriniz değişti mi?
Teklifimizde iki metrik önermiştik:
- bileşenle ilgili pull isteklerinin sayısı
- yeni katkıda bulunanlardan gelen pull isteklerinin sayısı
Eylül ayı için (taslak dokümanların yayınlanmasından sonraki ilk tam ay) içerikle ilgili çekme isteklerinde% 5 artış gördük (Ağustos'ta 20'den Eylül'de 21'e) ve katkıda bulunan üç yeni katılımcıyla birlikte Ağustos'ta iki pull isteği gönderen iki yeni katılımcıya kıyasla, toplam dört çekme talebi ilettiğimizi gördük. Bu metrikleri aylık olarak izlemeyi planlıyoruz.
Dokümanlar yayınlandıktan sonra üç ayda bir başlamak üzere toplamda üçten fazla katkı yapan kullanıcıların sayısını da 1 Ocak'tan itibaren takip edeceğiz.
Yeni bir katılımcı, PR'sinin yorumunda yeni bir katılımcının daha önce denediği ancak süreci anlamadığı için güncellemeyi tamamlamadığını belirttiği, yeni bir katılımcının PR'sinin yorumunda, yeni bir katılımcının Glorious Pickle malzeme veritabanına eklenmesinde bir fark yarattığını düşünüyoruz.
Analiz
Projede hangi süreçler yolunda gitti? Beklenmedik neydi? Ne tür güçlüklerle veya aksaklıkla karşılaştınız? Projenizin başarılı olduğunu düşünüyor musunuz? Neden evet veya neden hayır? (Bunu söylemek için henüz erkense projenizin başarısını ne zaman değerlendirebileceğinizi beklediğinizi açıklayın.)
Sezonluk Dokümanlar projemizin sonucundan çok memnunuz ve başarılı olduğumuzu düşünüyoruz. Yeni dokümanlar açık ve faydalıdır. Ayrıca, bileşenlerle ilgili pull isteklerinin ve katkıda bulunan yeni kullanıcılardan gelen pull isteklerinin sayısında şimdiden gözlemledik.
Orijinal teklifle ilgili geri bildirimde bulunarak ve yeni dokümanları taslak biçimde test ederek, neredeyse tüm Glorious Pickle topluluğunun katılımından da çok memnunuz.
Beklenmedik birkaç güçlükle karşılaştık: Sam'in eyaletindeki orman yangınlarının internet kesintisinden daha büyük bir zarara yol açmadığı için minnettarız. Ayrıca, @VinegarViv'i projeden kaybettiğimiz için üzgünüz. Kendisine ve ailesine iyi dileklerimizi iletiyoruz ve yakında tekrar görmeyi umuyoruz.
Sam belgeler üzerinde çalışmaya başlayana kadar fark etmediğimiz şeylerden biri turşuyla alakalı kaç tane terim ve kısaltmanın olduğu, hiç turşu yapma konusunda bilgi sahibi olmayan bir kişinin projemize yabancı olduğuydu. Ancak Sam, bilinmedik her terimin bir listesini tutmaya özen gösterdi ve bunları kendi araştırmaları aracılığıyla ve topluluk üyelerinden açıklamalar ve referanslar isteyerek tanımladı. Bu Pickle Sözlüğü, gelecekte daha fazla kişiyi turşulama topluluğuna davet etmemize çok yardımcı olacak.
Özet
2-4 paragrafta proje deneyiminizi özetleyin. Öğrendiklerinizi ve gelecekte neleri farklı yapmayı seçtiğinizi vurgulayın. Benzer bir sorunu belgelerle çözmeye çalışan diğer projelere ne tavsiye edersiniz?
Sözün kısası, lezzetli bir deneyim yaşadık! Belge 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ımız oldu. [Bunu yazmadım—Sam] Sam'in seçme konusunda bir geçmişi veya deneyimi olmasa da deneyimli bir teknik yazar olarak GitHub'la ilgili hiç bir deneyime sahip olmasa da yeni bir konuya dalma, soru sorma ve araştırma yapma konusunda rahattı. Sam yalnızca proje araçlarımızı (işleri takip etmek için kanban panosu kullanıyoruz) değil, aynı zamanda turşu şakalarımızı da hızlıca kavradı. Sam'in turşucu böceği yakalamasından ve topluluğumuza " şişelemesinden" çok mutluyuz.
Diğer projelere şunları öneriyoruz:
- Tekliflerinizin küçük ve yönetilebilir olmasını sağlayın. (Teklifimize başta tahmin cihazımızı endüstriyel toplu turşulama makineleriyle kullanma hakkındaki belgeleri dahil etmek istemiştik, ancak bunu dışarıda bırakmıştık çünkü açık kaynaklı turşu makineleriyle etkin bir şekilde çalışan topluluk üyelerimizden biri, program sırasında doktora tezini yazacaktı.) Cem'i meşgul edecek fazla işimiz oldu!
- Teknik yazar ararken ağlarınızdan yararlanın. Topluluğunuzdaki herkesten öneri isteyin. Sam'i Dokümanlar GitHub Sezonu boyunca bulmuş olsak da başvuru dönemi boyunca birkaç kişiyle görüştüğümüz için onlarla çalışırken kendimize güveniyorduk.
- Teknik yazarınızı topluluğunuza hoş geldiniz! Sam, Glorious Picklers'ın coşkulu tutumlarının soru sormayı kolaylaştırdığını bize bildirdi.
- Teknik yazarınızın açık kaynak becerileri kazanmasına yardımcı olun. Sam daha önce hiç Git kullanmamıştı, ancak birkaç eğiticiyi denedikten sonra hızlı bir şekilde hız kazandı. Sam, topluluktan ne kadar geri bildirim alabileceği ve bu geri bildirimi nasıl uygulayacağı konusunda endişeliydi, ancak topluluğumuzun "kaba fikir birliği" modeli ("tüm sorunlar ele alındığında fikir birliği elde edilir, ancak her zaman dikkate alınmayabilir"), Sam'in teknik yazım konusundaki uzmanlığını kullanarak eleştirileri ele alırken kendinden emin olmasını sağladı.
Ek
Bağlantı oluşturmak istediğiniz başka materyalleriniz varsa (örneğin, teknik yazarınızla çalışmak için paylaşmak istediğiniz bir sözleşme oluşturduysanız veya doküman projenizin şablonları ya da diğer açık belge kaynakları için buraya listeleyip bağlantı oluşturabilirsiniz). Ek'te, kullandığınız tüm belge araçları veya kaynakların bağlantılarını listelemek ya da yukarıdaki bölümlerde yer almayabilecek teşekkür veya bildirimleri eklemek için de uygun bir yerdir.
Tasdik
Ekibimiz, aşağıdaki kişilere ve konulara teşekkür etmek istiyor:
- @Dillicious, partnerine ve düşük müzik çalan hip hop radyosuna teşekkür etmek istiyor.
- @KimChiCook ona turşu yapmayı öğrettiği için 할머 kelimesi için teşekkür etmek istiyor
- @Piccalily, Chicago Manual of Style Online için teşekkür etmek istiyor
- @GherKen, üç çocuğuna, yapabildiği tüm turşuları yedikleri için teşekkür etmek istiyor
- @VinegarViv, programdan ayrıldığı için diğer ekip üyelerine teşekkür ediyor
- @BBChips, turşu olmayan en iyi yiyecek olan Tunnock's Karamel Gofret'e teşekkür etmek istiyor
- @Glorious PicklePat, bu projeyi üstlendiği için PickleDocs SIG'ye teşekkür ediyor
- Sam Scribe, tüm Glorious Pickle topluluğuna, özellikle de 2021 yazında kavanoz kavanozu doluyken kendilerine konserve kavanoz gönderen seçicilere teşekkür etmek istiyor. Bu, onları lezzetli turşularla tanıştırıyor.