Boke projesi

Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.

Proje özeti

Açık kaynak kuruluşu:
Bokeh
Teknik yazar:
vis_verborum
Proje adı:
Oluşturma, okuma, paylaşma: Bokeh'in belgelerini optimize etme
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

Oluşturma, okuma, paylaşma: Bokeh dokümanlarını optimize etme

1. Soyut

Bokeh, Python ile etkileşimli, tarayıcı tabanlı görselleştirmeler oluşturmak için son derece güçlü bir araçtır. Büyük bir kullanıcı tabanı (aylık 502 bin conda indirme, 855 bin PyPi indirme) ve çok sayıda katkıda bulunan (GitHub'da 455 katkıda bulunan) kişisi vardır. Bokeh'in kapsamlı dokümanlarının organik olarak büyütülmesi şaşırtıcı değil. Bu nedenle, bazı yerlerde tutarsız, erişmesi zor ve karmaşıktır.

Google'ın Dokümanlar Sezonu, Bokeh dokümanlarının yapısı ve içeriğinin odaklanmış bir şekilde incelenmesi ve düzeltilmesi, ayrıca dokümanların ve ilişkili araç ve iş akışlarının geleceğe hazır olmasının sağlanması için benzersiz bir fırsat sunar.

Python ve Sphinx ile açık kaynak projeleri kodladım ve belgeledim (en son: PyZillow ve PyPresseportal). Ancak Google Dokümanlar Sezonu'na katılımcı olarak katılmamı sağlayan şey gazetecilik geçmişim. 13 yıldan uzun süredir haber odalarında çalıştım. Bu sürenin büyük bir kısmında yönetici editör ve dijital değişimin savunucusu olarak görev yaptım. Gazetecilik görevlerimin yanı sıra yeni dijital araçları ve stil kılavuzlarını tasarlama ve belgeleme ile haber merkezi personelini eğitme konusunda giderek artan sorumluluklarım vardı.

Avrupa'dan ABD'ye taşındıktan sonra, iletişim ve kodlama konusundaki tutkumu bir araya getirmenin yeni yollarını araştırmaya karar verdim. Teknik yazmanın, yazma ve teknoloji alanındaki becerilerim ve deneyimlerimin en uygun kombinasyonu olduğunu düşünüyorum. Bu öneride, Bokeh'in belgelerini optimize etmek için Google'ın Dokümanlar Sezonu'nu nasıl kullanacağımı açıklayacağım: Dokümanları oluşturma ve dokümanlara katkıda bulunmayı daha kolay hale getirerek, dokümanları okumayı daha basit hale getirerek ve dokümanlardaki bilgileri başkalarıyla paylaşmayı kolaylaştırarak.

2. Mevcut durum

Bokeh'in resmi dokümanları şu ana birimlerden oluşur:

  • Anlatım dokümanları: Yükleme Kılavuzu, Kullanıcı Rehberi, Geliştirici Kılavuzu, Sürüm Notları
  • Galeri ve Demolar (kaynak kodlarıyla etkileşimli örnekler)
  • Referans Kılavuzu (belge dizelerine dayalı belgeler)
  • Eğitim (mybinder.org'da barındırılan kapsamlı Jupyter not defteri koleksiyonu)
  • IDE'ler için doküman dizeleri ve model yardımı
  • Proje deposundaki örnekler ve README dosyaları

Ayrıca, Bokeh'in geliştiricisinin kullanıcı sorularını aktif olarak yanıtladığı Bokeh destek forumunda ve Stack Overflow'da, ayrıca Bokeh'in Medium blogunda çok sayıda bilgi bulabilirsiniz.

Dokümanlar web sayfalarının çoğu, çeşitli standart ve özel Sphinx uzantıları kullanılarak Sphinx ile oluşturulur. Örneğin, Referans Kılavuzu, "autodoc" ve özel "bokeh_autodoc" gibi uzantılar kullanılarak docstring'lerden oluşturulur. Doğal olarak gelişen dokümanların doğası gereği, bu kılavuzda da yinelemeler ve tutarsızlıklar bulunur.

Mevcut belgeleri analiz ederken fark ettiğim ilk şeylerden biri, belge yazımı için açık stil yönergelerinin olmamasıydı. Bokeh Geliştirici Kılavuzu'nda bazı temel talimatlar yer alır. Ancak bu dokümanda, özellikle de açıklama metinlerinin ötesine geçen dokümanlar söz konusu olduğunda stil hakkında fazla bilgi verilmemiştir. Sonuç olarak, özellikle yeni gelenler için dokümanlardaki bilgilere erişmeyi zorlaştıran üslup ve yapı sorunları ortaya çıkıyor.

Örneğin:

Bokeh'in belgelendirme açılış sayfası oldukça kısa ve mevcut tüm kaynaklarla ilgili bilgi içermiyor (geniş doküman açıklamaları ve model yardım işlevleri kitaplığından, destek forumlarından, demolardan veya Medium blogundan bahsedilmiyor). Bu durum, yeni kullanıcıların Bokeh'i kullanmaya başlamasını da zorlaştırır.

3. Hedefler

On bir haftalık doküman geliştirme aşamasını en verimli şekilde kullanmak için üç önemli unsura odaklanacağım:

3.1. Doküman oluşturmayı iyileştirin

Bokeh'in dokümanlarının çoğu, yeni işlevler ve hata düzeltmeleri için çekme isteklerinin bir parçası olarak dokümanları ekleyen katkıda bulunanlar tarafından yazılmıştır. Mevcut dokümanları düzenlemek ve yeniden yapılandırmak için doküman geliştirme aşamasının bir kısmını kullanacağım. Bununla birlikte, dokümanları oluşturma ve sürdürmeyle ilgili iş akışlarını geleceğe hazır hale getirmeye de önem vereceğim. Katkıda bulunanların tutarlı bir şekilde yüksek standartlarda dokümanlar oluşturması mümkün olduğunca kolay olmalıdır.

Bunu iki yaklaşımla sağlayacağım:

  • Mevcut Geliştirici Kılavuzu'na eklenecek pratik ve basit bir stil kılavuzu oluşturacağım. Bu yönergeler stil, dil bilgisi ve yapı ile ilgilidir. Ayrıca, Bokeh'in katkıda bulunanlarının stil yönergelerinden haberdar olmasını sağlamak için Slack gibi şirket içi iletişim kanallarını kullanacağım. Ayrıca ekip için bire bir eğitim ve soru-cevap oturumları da sunacağım.
  • Bokeh'in PR'ler (pull request) ve CI (sürekli entegrasyon) için mevcut iş akışlarına eklenecek en uygun doküman kalitesi kontrolü araçlarını bulmak üzere çekirdek ekiple birlikte çalışacağım. Ekibin gereksinimlerine bağlı olarak bu, Bokeh'in test paketine, ön taahhüt ayarlarına veya GitHub işlemlerine pydocstyle, proselint ya da sphinxcontrib-spelling yazım denetimi gibi araçlar eklemek anlamına gelebilir. Açık kaynak projelerimden birine ait GitHub Actions'a çalışan bir kavram kanıtı ekledim.

3.2. Dokümanları okumayı iyileştirme

İyi dokümanların amacı, mevcut ve potansiyel kullanıcıların tam olarak doğru bilgileri bulmasını ve bu bilgilerden mümkün olduğunca verimli bir şekilde yararlanmasını kolaylaştırmaktır.

Bir metnin kullanılabilirliği açısından stil ve yapı önemli faktörlerdir: Belgeleri net ve tutarlı bir üslupla yazmak, okuyucuların dikkat dağıtıcı unsurlar ve gereksiz dil olmadan bilgileri hızlı bir şekilde edinmelerini sağlar. Dokümanların basit ve şeffaf yapısı, alakalı bilgileri hızlı bir şekilde bulmanızı kolaylaştırır.

Yeni kullanıcılar için kullanılabilirliği vurgulayarak her iki alana da odaklanacağım. Bu inceleme, kullanıcı kılavuzu odaklı anlatı dokümanlarının ayrıntılı bir incelemesini içerir. Ayrıca, farklı hedef kitlelere daha açık bir şekilde hitap etmek ve her kullanıcının doğru kaynaklara hızlı bir şekilde ulaşmasını sağlamak için belge açılış sayfasını elden geçireceğim.

Yukarıda özetlenen doküman oluşturma süreçlerini geliştirmeye olduğu gibi, gelecekte yapılacak iyileştirmeler için bir temel oluşturmaya ve Bokeh dokümanları için sürekli yüksek standartlara odaklanacağım.

3.3. Dokümanları paylaşma deneyimini iyileştirme

Üçüncü taraf platformlarda Bokeh hakkında daha fazla tartışma yapılıyor. Bu platformların çoğu, bağlantıların zengin önizlemelerini eklemek için Facebook'un OpenGraph gibi meta verileri kullanır. OpenGraph, Facebook, Twitter, LinkedIn, Slack ve iMessage gibi hizmetler tarafından kullanılır. Bokeh'in Discourse forumunda da bağlantı önizlemeleri oluşturmak için OpenGraph kullanılıyor.

Bu teknolojiden yararlanmak için #9792 numaralı sorunda açıklandığı gibi, Bokeh'in Sphinx tarafından oluşturulan web sayfalarına meta veri ekleyeceğim. En verimli yöntem, özel bir Sphinx uzantısı kullanmaktır. Birkaç gün önce, OpenGraph verileri için Sphinx uzantısının ilk sürümü GitHub'da yayınlandı. Bu uzantıyı Bokeh'in dokümanlarıyla birlikte kullanılacak şekilde iyileştirmeye yardımcı olmak için doküman geliştirme aşamasının bir kısmını kullanacağım.

Ayrıca, kendi açık kaynak projelerimden biri olan PyPresseportal'da başarıyla kullandığım bir kavram kanıtlama çalışması da hazırladım. Bu uzantı başlık, açıklama, resim ve URL gibi alakalı bilgileri otomatik olarak toplar. Daha sonra, bu bilgileri Sphinx tarafından oluşturulan HTML koduna OpenGraph etiketleri olarak ekler.

Bu uzantıyı geliştirmenin bir sonraki adımı, OpenGraph meta verilerini manuel olarak tanımlamak için özel yönergeler (docutil'in mevcut "meta" yönergelerine benzer) tanıtmaktır. Otomatik olarak oluşturulan meta veriler, manuel olarak girilen veri olmaması durumunda yalnızca yedek olarak kullanılır.

Yapılandırılmış verileri desteklemek çok daha karmaşık bir konu olduğundan, öncelikle Bokeh dokümanları için yüksek kaliteli OpenGraph meta verileri eklemeye odaklanacağım. OpenGraph'ı desteklemek için yapılan tüm çalışmalar aynı zamanda Yapılandırılmış Veri desteğinin temellerini de atar.

Sphinx ve ReadTheDocs topluluklarının üyeleri, OpenGraph ve Yapılandırılmış Veriler için uzantı geliştirmek istediklerini belirtmiştir (ör. #1758 ve #5208 sorunları). Onlarla yakın bir şekilde çalışacağımızdan emin olabilirsiniz.

4. Teslim edilecek materyaller

Özetlemek gerekirse, Season of Docs'un sonucunda elde etmeyi umduğumuz sonuçlar şunlardır:

  • Bokeh katkıda bulunanları için doküman stili yönergeleri
  • PR ve CI iş akışları, otomatik belgeleme kalite kontrolünü içerecek şekilde yeniden düzenlendi
  • Düzenlenmiş ve yeniden yapılandırılmış Kullanıcı Kılavuzu
  • Düzeltilmiş dokümanlar açılış sayfası
  • Dokümantasyon web sayfalarında ve çalışan bir Sphinx uzantısında yer alan OpenGraph meta verileri

Ayrıca, Google'ın Dokümanlar Sezonu'ndaki yolculuğumu kişisel web sitemde/Medium'da veya Bokeh'in Medium blog'unda belgelemek için bir "doküman günlüğü" tutacağım. Bu, Google için proje raporuna da temel olur. Mümkün olduğunda tüm çalışmaları GitHub sorunları ve pull isteği şeklinde şeffaf bir şekilde yapacağım.

5. Zaman çizelgesi

Toplulukla bağ kurma aşamasından önce: Bokeh'in GitHub deposunda çeşitli tartışmalara aktif olarak katılıyorum ve Bokeh'in Google Dokümanlar Sezonu'ndaki mentorları Bryan Van de Ven ve Pavithra Eswaramoorthy ile iletişim halindeyim. Bokeh ile ilgili konuşmaya etkin şekilde devam edeceğim ve görselleştirmeler oluşturarak ve yayınlayarak Bokeh hakkında daha fazla bilgi edineceğim.

Topluluk bağları oluşturma aşaması (17 Ağustos - 13 Eylül):

  • Temel ekibi tanıma, mentorlarla birlikte proje planını hassaslaştırma
  • Düzenli raporlama ve mentorlarla geri bildirim için bir program ve iletişim kanalları oluşturun
  • Bokeh'in Slack kanalında aktif olarak yer alarak Google'ın Dokümanlar Sezonu ve doküman geliştirme aşamasının hedefleri hakkında ilgili tüm Bokeh katkıda bulunanlarını bilgilendirin.
  • Belge geliştirme aşamasıyla ilgili planı daha da iyileştirmek için Bokeh'e katkıda bulunan kullanıcılardan geri bildirim alın

Belge geliştirme aşaması

1. Hafta, 14/09 - 20/09:

  • Anlatım belgelerini denetlemeye ve düzenlemeye başlayın
  • Stil yönergelerinin taslağını oluşturmaya başlayın

2. Hafta, 21/09 - 27/09:

  • Stil yönergeleri üzerinde çalışmaya devam edin
  • Anlatım belgelerini düzenlemeye devam edin
  • Belgelerin açılış sayfasını baştan tasarlamaya başlayın

3. Hafta, 28.09 - 04.10:

  • Stil yönergelerini kesinleştirin
  • Doküman açılış sayfasını tamamlama

4. Hafta, 5/10 - 11/10:

  • Açıklayıcı dokümanların düzenlenmesini tamamlama
  • PR/CI iş akışlarına belge kalitesi kontrolüne yönelik araçların entegre edilmesi hakkında Bokeh çekirdek ekibiyle görüşme

5. Hafta, 12-18 Ekim:

  • Slack'te Bokeh katkıda bulunanlarla soru-cevap oturumu düzenleyerek stil kurallarını, anlatım dokümanlarındaki iyileştirmeleri ve PR/CI iş akışlarını bir araya getirin
  • OpenGraph meta verileri için mevcut kavram kanıtlamamı dağıtılabilir bir Sphinx uzantısı haline getirmeye başlama
  • Bokeh katkıda bulunanlarıyla yapılan soru-cevap oturumundan elde edilen geri bildirimlere göre stil yönergelerini gözden geçirme

6. Hafta, 19/10 - 25/10:

  • PR ve CI iş akışlarında doküman kalite kontrolü araçlarının testine başlama
  • Meta veriler için Sphinx uzantısı geliştirmeye devam edin

7. Hafta, 26/10 - 01/11:

  • Sfenks uzantısını test etme
  • Slack'te Bokeh katkıda bulunanlarıyla ikinci soru-cevap oturumu
  • İkinci soru-cevap oturumundan gelen geri bildirime göre teslim edilecek materyalleri gözden geçirin.

8. Hafta, 11/02 - 11/08:

  • Sphinx uzantısını dağıtın ve iyileştirilmiş anlatım dokümanlarını ve doküman açılış sayfasını yayınlayın

9. Hafta, 9 Kasım - 15 Kasım:

  • Belge kalite kontrol araçlarını PR ve CI iş akışlarına dağıtma
  • Geliştirici Kılavuzu'nu, stil yönergeleri ve PR ile CI iş akışı eklemeleri içerecek şekilde güncelleyip yayınlayın

10. hafta, 16/11 - 22/11:

  • Kalan görevleri tamamlama

11. Hafta, 23-29 Kasım:

  • Proje raporu yazmaya başlayın
  • Proje değerlendirme yazmaya başlayın

Projenin tamamlanma aşaması

12. Hafta, 30.11 - 05.12:

  • Proje raporunu tamamlayıp gönderme

13. Hafta, 03.12 - 10.12:

  • Proje değerlendirmesini tamamlayıp gönderme

Google Dokümanlar Sezonu sona erdikten sonra:

  • Bokeh'in geliştirilmesine ve dokümanları üzerinde çalışmaya devam etmeyi umuyorum.
  • OpenGraph/Yapılandırılmış Veri meta verileri için Sphinx uzantısı geliştirmeye devam etmeyi planlıyorum.
  • Bokeh'i veri gazeteciliğinde bir araç olarak tanıtmak için gazetecilik geçmişimden ve mevcut ağımdan yararlanmayı umuyorum. Örneğin, habercilik kitlesini göz önünde bulundurarak Boke hakkında yazabilir veya Bokeh'in gazetecilik ortamında kullanımıyla ilgili konferans konuşmaları yapabilirsiniz.

6. Hakkımda

Aslen televizyon, internet ve radyo haberciliği alanında deneyim sahibi bir gazeteciyim. TV ve dijital haberlerde yönetici editör ve muhabir olarak çalışarak yazma ve düzenleme konusunda yıllarca deneyim kazandım. Aynı zamanda dijital dönüşümü ve otomasyonu destekleyen çeşitli projelerde çalıştım. Dijital haber markaları için dijital araçları ve iş akışlarını, stil kılavuzlarını ve iletişim stratejilerini kapsayan çok sayıda kılavuz yazdım. Ayrıca ekip üyelerini bu araçların kullanımı konusunda eğittim.

İletişim ve teknolojinin kesişim noktalarına her zaman ilgi duydum. Python'da kod yazmayı öğrendiğimde yepyeni bir dünya açıldı: Örneğin, veri gazeteciliği için veri analizi ve görselleştirme yapabildim. Kod yazmayı öğrenmek, haber merkezi iş akışları için dijital araçlar geliştirmek amacıyla yazılım mühendisleriyle aktif olarak çalışmamı da sağladı.

Önceki işimde yazdığım kılavuzlar ve dokümanlar maalesef herkese açık değil. Bu nedenle, şu anda açık kaynak projelere daha fazla dahil olmaya odaklanıyorum (örnekler için aşağıya bakın). Teknik yazım konusundaki çalışmalarımda Google'ın geliştirici dokümanlarıyla ilgili stil kılavuzu ve Microsoft stil kılavuzu gibi stil kılavuzlarından yararlandım. GitHub, Slack ve Linux'u düzenli olarak kullanıyorum. Sphinx, Mypy ve Sphinx autodoc gibi araçları kullanarak anlatım dokümanları, docstring'lar ve tür ipuçları yazıyorum.

Şu anda serbest çalışıyorum. Programım, doküman geliştirme aşamasında Bokeh'in dokümanlarıyla haftada yaklaşık 25 saat çalışmak için gerekli esnekliği sağlıyor. Pasifik Saat Dilimi'nde çalışıyorum ancak ekibin programlarına ve ihtiyaçlarına uymaktan memnuniyet duyarım.

7. Son açık kaynak doküman örnekleri

  • PyZillow: PyZillow, Zillow.com emlak web sitesinin API'si için bir Python sarmalayıcısıdır. Bazı kodlar sağlamanın ve kod koruyucularından biri olarak hareket etmenin yanı sıra tüm dokümanları yazdım. Sphinx'i anlatım dokümanları ve modül referansı için de kullandım. Modül referansını, Sphinx uzantısı autodoc ile koda eklediğim docstring'lere göre oluşturdum.

  • PyPresseportal: PyPresseportal, presseportal.de web sitesinin API'si için bir Python sarmalayıcısıdır. presseportal.de web sitesi, Almanya'da basın bültenleri ve yatırımcı ilişkileri duyurularının en büyük distribütörlerinden biridir. Örneğin, neredeyse tüm polis ve itfaiye departmanları basın bültenlerini dağıtmak için bu hizmeti kullanır. API'yi gazeteci olarak uzun yıllar kullandıktan sonra, web sitesinin kapsamlı veri kaynaklarına Python nesneleri olarak erişmek için bir Python arayüzü geliştirmeye karar verdim. Kodu ve Sphinx tabanlı dokümanların tamamını yazdım.