Boke projesi

Bu sayfa, Google Dokümanlar Sezonu için kabul edilen teknik yazı projesinin ayrıntılarını içerir.

Proje özeti

Açık kaynak kuruluşu:
Boke
Teknik yazar:
vis_verborum
Proje adı:
Oluşturma, okuma, paylaşma: Bokeh dokümanlarını optimize etme
Proje süresi:
Standart uzunluk (3 ay)

Proje açıklaması

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

1. Özet

Bokeh, Python ile etkileşimli, tarayıcı tabanlı görselleştirmeler oluşturmak için son derece güçlü bir araçtır. Çok büyük bir kullanıcı tabanına (aylık 502 bin conda indirme, 855 bin PyPi indirme) ve çok sayıda katkıda bulunana (GitHub'da 455 katkıda bulunan) sahiptir. Bokeh'in kapsamlı belgelerinin doğal bir şekilde gelişmesi şaşırtıcı değil. Dolayısıyla, bazı yerlerde tutarsız, erişilmesi zor ve karışık olabilir.

Google Dokümanlar Sezonu, Bokeh dokümanlarının yapısı ve içeriğinin odaklanarak gözden geçirilmesi ve revizyonu yapılması, ayrıca belgelerin ve ilişkili araçlar ile iş akışlarının geleceğe hazır olduğundan emin olunması açısından benzersiz bir fırsat sunar.

Python ve Sphinx ile (en son PyZillow ve PyPresseportal) açık kaynaklı projeleri kodlayıp belgeledim. Ancak beni Google Dokümanlar Sezonu'na benzersiz bir katılımcı olarak ayıran şey gazetecilik geçmişim: 13 yıldan uzun bir süre haber merkezlerinde çalıştım. Yıllarca dijital değişimin savunucusu ve yönetici editörü oldum. Gazetecilik görevlerimin yanı sıra yeni dijital araçların ve stil kılavuzlarının tasarlanıp belgelenmesi ve haber merkezi personelinin eğitimi ile ilgili sorumluluklarım giderek artıyordu.

Kısa süre önce Avrupa'dan ABD'ye taşındıktan sonra, iletişim ve kodlamaya duyduğum tutkuyu bir araya getirmenin yeni yollarını aramaya karar verdim. Teknik yazı yazmanın, yazılı ve teknoloji alanındaki becerilerim ile deneyimlerim arasında en uygun kombinasyonu olduğunu düşünüyorum. Bu teklifte, Bokeh'nin dokümanlarını optimize etmek için Google Dokümanlar'ın Sezonu'nu nasıl kullanacağımı açıklayacağım: Dokümanları oluşturmayı ve dokümanlara katkıda bulunmayı daha kolay hale getirerek, dokümanları okumayı ve dokümanlardaki bilgileri başkalarıyla daha kolay bir şekilde paylaşmayı kolaylaştırarak.

2. Mevcut durum

Bokeh’in resmi belgeleri aşağıdaki 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 (docstrings tabanlı belgeler)
  • Eğitim (mybinder.org üzerinde barındırılan kapsamlı Jupyter not defterleri koleksiyonu)
  • IDE'ler için doküman dizeleri ve model yardımı
  • Proje deposundaki örnekler ve README'ler

Ayrıca, Bokeh destek forumu ve Bokeh'in geliştiricisinin kullanıcı sorularını aktif olarak yanıtladığı Stack Overflow'da ve Bokeh'in Medium blogunda çok fazla bilgi bulunmaktadır.

Belgelerle ilgili web sayfalarının çoğu, çeşitli standart ve özel Sfenks uzantıları kullanılarak Sfenks ile oluşturulmuştur. Örneğin, Referans Kılavuzu "autodoc" ve özel "bokeh_autodoc" gibi uzantılar kullanılarak doküman dizelerinden oluşturulur. Doğal biçimde gelişen belgelerin doğasında olduğu gibi, gereksiz öğeler ve tutarsızlıklar içerir.

Mevcut dokümanları analiz ederken fark ettiğim ilk şeylerden biri belge yazımı için net stil yönergelerinin olmamasıydı. Bokeh Geliştirici Kılavuzu, bazı temel talimatlar içerir. Ancak, bu belge stil hakkında, özellikle de doküman dizelerinin ötesine geçen belgelere ilişkin çok fazla bilgi içermiyor. Sonuç olarak biçimle ilgili ve yapısal sorunlar, özellikle yeni başlayanlar için dokümanlardaki bilgilere erişmeyi zorlaştırıyor.

Örneğin:

Bokeh'nin dokümantasyon açılış sayfası çok kısa ve mevcut tüm kaynaklar hakkında bilgi içermiyor (doküman dizelerinden ve model yardım işlevlerinden oluşan kapsamlı kitaplıktan, destek forumlarından, demolardan veya Medium blogundan bahsedilmiyor). Bu durum, yeni kullanıcıların Bokeh'i kullanmaya başlamalarını da zorlaştırır.

3. Hedefler

On bir haftalık belge geliştirme aşamasını en verimli şekilde değerlendirmek için üç temel unsura odaklanacağım:

3.1. Doküman oluşturma sürecini iyileştirin

Bokeh dokümanlarının çoğu, yeni işlevler ve hata düzeltmeleri için pull isteklerinin bir parçası olarak dokümanlara yer veren katkıda bulunanlar tarafından yazılmıştır. Mevcut belgeleri düzenlemek ve yeniden düzenlemek için doküman geliştirme aşamalarının bir kısmını kullanacak olsak da, belgeleri oluşturma ve sürdürmeye yönelik iş akışlarını geleceğe hazırlamanın önemini vurgulayacağım: Katkıda bulunanlar için, belgelemenin sürekli olarak yüksek standartta tutulması mümkün olduğunca kolay olmalıdır.

Bunu iki yaklaşımla gerçekleştireceğim:

  • Mevcut Geliştirici Kılavuzu'nda yer alacak bir dizi pratik ve basit stil yönergesi oluşturacağım. Bu yönergeler stil, dil bilgisi ve yapıyı ele alır. Buna ek olarak, Bokeh'deki katkıda bulunanların stil kurallarından haberdar olduğundan emin olmak için Slack gibi şirket içi iletişim kanallarını kullanacağım. Ayrıca ekibe bire bir eğitimler ve soru-cevap oturumları da yapacağım.
  • Çekirdek ekiple çalışarak belge kalite kontrolü için ideal araç seti bulmak üzere çalışacağım. Bu araçlar, PR'ler (Çekme istekleri) ve CI (sürekli entegrasyon) için Bokeh'in mevcut iş akışlarına eklenecek. Ekibin gereksinimlerine bağlı olarak bu, Bokeh'in test paketine, taahhüt öncesi kurulumuna veya GitHub işlemlerine pydocstyle, proselint veya sphinxcontrib-spelling yazım denetimi gibi araçlar eklemek anlamına gelebilir. Kendi açık kaynak projelerimden birinin GitHub işlemlerine çalışan bir kavram kanıtlama ekledim.

3.2. Dokümanları okumayı iyileştirin

İyi bir belgelemenin 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 yararlanabilmesini sağlamaktır.

Bir metnin kullanılabilirliğine ilişkin en önemli faktörler stili ve yapısıdır: Belgeleri açık ve tutarlı bir tarzda yazmak, okuyucuların bilgileri dikkat dağıtıcı unsurlar olmadan ve gereksiz dil kullanmadan hızlıca kavramasına olanak tanır. Belgelerin basit ve şeffaf yapısı ilgili bilgilerin hızlı bir şekilde bulunmasını kolaylaştırır.

Yeni kullanıcılar için kullanılabilirliği ön plana çıkararak bu iki alana da odaklanacağım. Bu çalışmada, anlatım belgelerinin kapsamlı bir incelemesi, Kullanıcı Rehberi'nde toplanmıştır. Ayrıca farklı hedef kitleleri daha net bir şekilde ele almak ve her kullanıcının doğru kaynaklara hızla ulaşmasını sağlamak için belgenin açılış sayfasını da elden geçirdim.

Yukarıda özetlenen doküman oluşturma iyileştirmeleri gibi, gelecekte yapılacak iyileştirmeler için bir temel oluşturmaya ve Bokeh belgeleri için sürekli olarak yüksek standartlara odaklanacağım.

3.3. Dokümanların paylaşımını iyileştirin

Üçüncü taraf platformlarda Bokeh hakkında giderek daha fazla tartışma yapılıyor. Bu platformların birçoğu, bağlantıların zengin önizlemelerini eklemek için Facebook 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ı konuda açıklandığı gibi Bokeh Sfenks tarafından oluşturulan web sayfalarına meta veri ekleyeceğim. En etkili yol özel bir Sfenks uzantısı kullanmaktır. Birkaç gün önce, OpenGraph verileri için bir Sphinx uzantısının ilk sürümü GitHub'da yayınlandı. Bu uzantıyı Bokeh dokümanlarıyla kullanmak üzere geliştirmeye yardımcı olması için bazı doküman geliştirme aşamasından yararlanacağım.

Ayrıca, kendi açık kaynak projelerimden biri olan PyPresseportal'da başarıyla kullandığım bir kavram kanıtlama oluşturdum. Bu uzantı başlık, açıklama, resim ve URL gibi alakalı bilgileri otomatik olarak toplar. Ardından bu bilgileri Sfenks'in oluşturduğu HTML koduna OpenGraph etiketleri olarak ekler.

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

Yapılandırılmış Verilerin desteklenmesi çok daha karmaşıktır. Bu nedenle, öncelikle Bokeh belgeleri 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 oluşturacaktır.

Sphinx ve ReadTheDokümanlar topluluklarının üyeleri, OpenGraph ve Yapılandırılmış Veriler için uzantılar (ör. #1758 ve #5208 konularında) geliştirmeyle ilgilendiklerini ifade etmiştir. Bu üyelerle yakın bir çalışma yürüteceğim.

4. Teslim edilecek materyaller

Özetlemek gerekirse Dokümanlar Sezonundan çıkmayı beklediğim teslimatlar şunlardır:

  • Bokeh ile katkıda bulunanlar için doküman stili kuralları
  • PR ve CI iş akışları, otomatik belge kalite denetimini içerecek şekilde yeniden düzenlendi
  • Kullanıcı Rehberi düzenlendi ve yeniden yapılandırıldı
  • Gözden geçirilmiş belgeler açılış sayfası
  • Belgeler web sayfalarında bulunan OpenGraph meta verileri ve çalışan bir Sphinx uzantısı

Buna ek olarak, Google Dokümanlar Sezonu'ndaki yolculuğumu kişisel web sitemde/Medium veya Bokeh’s Medium blogunda belgelemek üzere bir "doclog" tutacağım. Bu bilgiler Google'ın proje raporuna da temel oluşturur. GitHub ile ilgili sorunlar ve pull isteği konusunda mümkün olduğunca şeffaf bir şekilde çalışacağım.

5. Zaman çizelgesi

Topluluk bağ kurma aşamasından önce: Bokeh'in GitHub deposunda aktif olarak çeşitli tartışmalara katılıyorum ve Bryan Van de Ven ile Bokeh'in Google Dokümanlar Sezonu'nda Bokeh'in mentorları Pavithra Eswaramoorthy ile irtibat halindeydim. Bokeh ile ilgili görüşmelerimde aktif kalacağım ve görselleştirmeler oluşturup yayınlayarak Bokeh ile ilgili kendimi daha iyi tanıyacağım.

Toplulukla bağ aşaması (17.08-13.09):

  • Çekirdek ekibi tanımak, mentorlar karşılığında proje planını geliştirmek
  • Mentorlardan düzenli aralıklarla rapor almak ve geri bildirim vermek için bir program ve iletişim kanalları oluşturun
  • Bokeh Slack'te aktif olarak yer alan ve Bokeh ile ilgilenen herkesi Google Dokümanlar Sezonu ve doküman geliştirme aşaması hedefleri hakkında bilgilendirmek için
  • Belge geliştirme aşaması planını daha da geliştirmek için Bokeh ile katkıda bulunan kişilerden geri bildirim alın

Belge geliştirme aşaması

1. Hafta, 14.09 - 20.09:

  • Anlatıma ilişkin dokümanları denetlemeye ve düzenlemeye başlayın
  • Stil yönergeleri taslağı hazırlamaya başlayın

2. Hafta, 21.09 - 27.09:

  • Stil yönergeleri üzerinde çalışmaya devam et
  • Anlatım belgelerini düzenlemeye devam et
  • Belge açılış sayfasını revizyondan geçirmeye başlayın

3. Hafta, 28.09-10.04:

  • Stil kurallarını tamamlama
  • Belge tamamlama açılış sayfası

4. Hafta, 05.10.2011:

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

5. Hafta, 10.10 - 18.10:

  • Stil kuralları, anlatım belgelerine yönelik iyileştirmeler ve PR/CI iş akışları hakkında konuşmak için Slack'te Bokeh'e katkıda bulunanlarla soru-cevap oturumu düzenleyin
  • OpenGraph meta verileri için mevcut kavram kanıtlamamı dağıtılabilir bir Sphinx uzantısına dönüştürmeye başla
  • Bokeh ile katkıda bulunan kullanıcılarla yapılan Soru-Cevap oturumundaki geri bildirimlere dayalı olarak stil kurallarını gözden geçirin

6. Hafta, 19 Ekim - 25 Ekim:

  • PR ve CI iş akışlarında belge kalitesi kontrolü araçlarını test etmeye başlayın.
  • Meta veriler için Sphinx uzantısının geliştirmeye devam edilmesi

7. Hafta, 26.10 - 01.11:

  • Sfenks uzantısı testi
  • Slack'te Bokeh katkıda bulunanlarla ikinci soru-cevap oturumu
  • İkinci Soru-Cevap oturumundaki geri bildirimlere göre teslimatları gözden geçirmek

8. Hafta, 02.11.- 08.11:

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

9. Hafta, 09.11 - 15.11:

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

10. Hafta, 16.11.- 22.11:

  • Kalan görevleri tamamlayın

11. Hafta, 23.11 - 29.11:

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

Projeyi kesinleştirme aşaması

12. Hafta, 30 Ekim - 05.12:

  • Proje raporunu sonuçlandırma ve gönderme

13. Hafta, 12.03 - 10.12:

  • Proje değerlendirmesini sonuçlandırma ve gönderme

Google Dokümanlar Sezonu bittikten sonra:

  • Bokeh'in geliştirilmesinde yer almayı ve Bokeh dokümanları üzerinde çalışmaya devam etmeyi umuyorum.
  • OpenGraph/Yapılandırılmış Veri meta verileri için bir Sphinx uzantısı geliştirmeye devam etmeyi planlıyorum.
  • Gazetecilik geçmişimi ve mevcut ağımı kullanarak Bokeh'i veri gazeteciliğinde bir araç olarak tanıtmayı umuyorum. Örneğin, gazetecilik kitlesini düşünerek Bokeh hakkında yazılar yazabilir veya gazetecilik ortamlarında Bokeh kullanımı hakkında konferans konuşmaları sunabilir.

6. Hakkımda

Geçmişte TV, internet ve radyo haberleri alanında çalışan bir gazeteciyim. Televizyonda ve dijital haberlerde editör ve muhabir olarak çalışmak bana yazı ve düzenleme alanında yıllarca deneyim kazandırdı. Aynı zamanda dijital dönüşüm ve otomasyonu destekleyen birkaç projede çalıştım. Dijital araçların ve iş akışlarının yanı sıra dijital haber markaları için stil kılavuzları ve iletişim stratejileri içeren çok sayıda kılavuz yazdım. Ayrıca ekip üyelerine bu araçların kullanımı konusunda eğitim verdim.

İletişim ve teknoloji arasındaki kesişim noktaları hep ilgimi çekmiştir. Python'da kod yazmayı öğrendiğimde bambaşka bir dünyanın kapılarını açtı: Örneğin, veri gazeteciliği için veri analizi ve görselleştirme yapabildim. Kodlamayı öğrenmek, haber merkezi iş akışları için dijital araçlar geliştirmek üzere yazılım mühendisleriyle aktif şekilde çalışmama da olanak tanıdı.

Önceki işimde yazdığım kılavuzlar ve belgeler maalesef herkese açık değil. Bu nedenle, şimdi açık kaynaklı projelerde daha fazla yer almaya odaklanıyorum (örnekleri aşağıda görebilirsiniz). Teknik yazımdaki çalışmalarımı Google'ın geliştirici dokümanları stil kılavuzu ve Microsoft stil kılavuzu gibi stil kılavuzlarına dayandırdım. GitHub, Slack ve Linux'u düzenli olarak kullanıyorum. Sfenks, Mypy ve Sfenks autodoc gibi araçları kullanarak anlatımlı dokümanlar, doküman dizeleri ve ipuçları yazıyordum.

Şu anda serbest olarak çalışıyorum. Programım doküman geliştirme aşamasında Bokeh’in belgeleri üzerinde haftada yaklaşık 25 saat çalışmak için gerekli esnekliği sağlıyor. Pasifik Saat Diliminde çalışıyorum ancak ekibin programlarını ve ihtiyaçlarını karşılamaktan memnuniyet duyuyorum.

7. Son açık kaynak belge örnekleri

  • PyZillow: PyZillow, Zillow.com adlı emlak web sitesinin API'si için bir Python sarmalayıcıdır. Kod sağlama ve kod sorumlularından biri olmanın yanı sıra belgelerin tamamını da yazdım. Anlatım dokümanları ve modül referansı için Sfenks'i kullandım. Koda eklediğim doküman dizelerini temel alarak, Sphinx uzantısı autodoc ile modül referansını oluşturdum.

  • PyPresseportal: Py Presseportal, web sitesi presseportal.de sitesinin API'si için bir Python sarmalayıcıdır. Presseportal.de web sitesi, Almanya'daki basın bültenlerinin 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 yıllarca gazeteci olarak 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 Sfenks tabanlı tüm dokümanları ben yazdım.