Boke projesi

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

Proje özeti

Açık kaynak kuruluşu:
Bokeh
Teknik yazar:
vis_verborum
Projenin 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. Büyük bir kullanıcı tabanına (aylık 502 bin conda indirme, 855 bin PyPi indirme) ve çok sayıda katılımcıya (GitHub'da 455 katkıda bulunan kullanıcı) sahiptir. Bokeh’nin kapsamlı belgelerinin doğal bir şekilde gelişmesi pek şaşırtıcı değil. Bu da tutarsız, ulaşılması zor ve karmaşık bir durum söz konusu.

Google Dokümanlar Sezonu, Bokeh dokümanlarının yapısına ve içeriğine odaklanılan bir inceleme ve düzeltme süreci için benzersiz bir fırsat sunar. Aynı zamanda, söz konusu belgeler ve ilişkili araçlar ile iş akışlarının geleceğe hazır olması açısından da benzersiz bir fırsat sunar.

Python ve Sphinx ile (en son PyZillow ve PyPresseportal) açık kaynak projeleri kodlayıp belgeledim. Ama benim gazetecilik geçmişim, beni Google Dokümanlar Mevsimi'ne benzersiz bir katılımcı yapıyor: 13 yıldan uzun bir süre haber merkezlerinde çalıştım ve yıllarca baş editörlük yaptım ve dijital değişimin savunucusu oldum. Gazetecilik görevlerimin yanı sıra yeni dijital araçların ve stil kılavuzlarının tasarlanması ve belgelenmesi ve haber merkezi personelinin eğitimiyle ilgili sorumluluklarım da arttı.

Kısa süre önce Avrupa'dan ABD'ye taşındıktan sonra, iletişim ve kodlamaya duyduğum heyecanı bir araya getirmenin yeni yollarını aramaya karar verdim. Teknik yazı yazmanın, hem yazı hem de teknoloji alanındaki becerilerim ile deneyimlerim arasında en iyi birleşimi olduğunu düşünüyorum. Bu teklifte, Bokeh dokümanlarını optimize etmek için Google Dokümanlar 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’nin 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 dizeler ve model yardımı
  • Proje deposundaki örnekler ve README'ler

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

Belgeleme 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. Organik olarak büyütülen belgelerin doğası gibi, gereksiz bilgiler ve tutarsızlıklar içerir.

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 bazı temel talimatlar içerir. Ancak bu belge stil hakkında, özellikle de doküman dizesinin ötesine geçen belgelerle ilgili çok fazla bilgi içermiyor. Bu nedenle, biçimle ilgili ve yapısal sorunlar özellikle yeni başlayanlar için dokümanlardaki bilgilere erişimi zorlaştırıyor.

Örneğin:

Bokeh’nin dokümantasyon açılış sayfası oldukça kısa olup mevcut tüm kaynaklar hakkında bilgi içermez (Dökümanlar ile model yardım işlevlerinden oluşan kapsamlı kitaplıktan, destek forumlarından, demolardan veya Medium blogundan bahsedilmemiştir). Bu durum, yeni kullanıcıların Bokeh özelliğini kullanmaya başlamalarını da zorlaştırır.

3. Goller

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

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

Bokeh ile ilgili belgelerin çoğu, yeni işlevler için pull istekleri ve hata düzeltmeleri kapsamında dokümanlara yer veren katkıda bulunanlar tarafından yazılmıştır. Mevcut dokümanları düzenlemek ve yeniden düzenlemek için belge geliştirme aşamalarının bir kısmını kullanacak olsam da, belgeleri oluşturma ve sürdürmeye ilişkin iş akışlarının geleceğin kanıtı olmasını sağlama konusunu vurgulayacağım: Katkıda bulunanlar için sürekli yüksek bir belgeleme standardını korumak mümkün olduğunca kolay olmalıdır.

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

  • Mevcut Geliştirici Kılavuzu'nda yer alacak pratik ve basit bir stil yönergesi oluşturacağım. Bu yönergeler stil, dil bilgisi ve yapıyı ele alır. Buna ek olarak, Bokeh'deki katılımcıların stil kurallarından haberdar olmasını sağlamak için Slack gibi şirket içi iletişim kanallarını da kullanacağım. Ayrıca ekip için bire bir eğitim ve Soru-Cevap oturumları da sağlayacağım.
  • Çekirdek ekibiyle birlikte çalışarak belge kalitesi kontrolü için ideal araç seti bulmak üzere çalışacağım. Bu araçlar, Bokeh'nin PR'ler (alınma istekleri) ve CI (sürekli entegrasyon) için mevcut iş akışlarına eklenecek. Ekibin gereksinimlerine bağlı olarak bu, Bokeh'nin test paketine, taahhüt öncesi kurulumuna veya GitHub işlemlerine pydocstyle, proselint veya sfenxcontrib-yazım denetimi gibi araçların eklenmesi 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 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 yararlanmasını sağlamaktır.

Bir metnin kullanılabilirliğini belirleyen önemli faktörler metinlerin tarzı ve yapısıdır: Belgeleri açık ve tutarlı bir üslupla yazmak, okuyucuların bilgileri fazla dikkat dağıtıcı unsurlar olmadan ve gereksiz dil kullanmadan hızlıca kavrayabilmesini sağlar. Belgelerin basit ve şeffaf bir 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, Kullanıcı Rehberi'ni merkez alarak anlatıma ilişkin dokümanların kapsamlı bir incelemesini içerir. Ayrıca farklı hedef kitlelere daha net 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ı da elden geçirdim.

Yukarıda özetlenen belgelerin oluşturulmasında olduğu 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'un Discourse forumunda da bağlantı önizlemeleri oluşturmak için OpenGraph kullanılıyor.

Bu teknolojiden yararlanmak için #9792 sorununda açıklandığı gibi, Bokeh'nin 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 birlikte kullanmak üzere iyileştirmeye yardımcı olmak için bazı doküman geliştirme aşamalarından faydalanacağım.

Ayrıca, kendi açık kaynak projelerimden biri olan PyPresseportal'da başarıyla kullandığım bir kavram kanıtlama hazırladım. 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 manuel olarak tanımlamak için özel yönergeler eklemektir (docutil'in mevcut "meta" yönergelerine benzer). Otomatik olarak oluşturulan meta veriler, manuel olarak girilen verilerin olmaması durumunda yalnızca yedek olarak kullanılır.

Yapılandırılmış Verileri desteklemek çok daha karmaşıktır; bu nedenle, ö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 temelini oluşturacaktır.

Sphinx ve ReadTheDocument topluluklarının üyeleri, OpenGraph ve Yapılandırılmış Veriler (ör. #1758 ve #5208 numaralı sorunlarda) için uzantılar geliştirmeyle ilgilenmektedir. Kendileriyle yakın işbirliği içinde çalışacağım.

4. Teslim edilecek materyaller

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

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

Buna ek olarak, Google Dokümanlar Mevsimi'ndeki yolculuğumu kişisel web sitemde/Medium veya Bokeh Medium blogunda belgelemek üzere bir “doclog” tutacağım. Bu ayrıca Google için proje raporu için bir temel oluşturur. Mümkün olduğunda GitHub sorunları ve pull isteği konusunda tüm işleri şeffaf bir şekilde yapacağım.

5. Zaman çizelgesi

Topluluk bağlama aşamasından önce: Bokeh'nin GitHub deposunda aktif olarak çeşitli tartışmalara katılıyorum ve Google Dokümanlar Mevsimi için Bokeh'ün danışmanları Bryan Van de Ven ve Pavithra Eswaramoorthy ile iletişime geçtim. Bokeh ile ilgili görüşmelerimde aktif olacağım ve görseller oluşturup yayınlayarak Bokeh hakkında daha fazla bilgi edineceğim.

Toplulukla bağ aşaması (17 Ağustos - 13 Eylül):

  • Çekirdek ekibi tanıyın, mentorlar karşılığında proje planını iyileştirin
  • Mentorlardan düzenli olarak rapor almak ve geri bildirim vermek için bir program ve iletişim kanalları oluşturun.
  • Bokeh ile ilgilenen tüm Bokeh katkıda bulunanları Google Dokümanlar Sezonu ve doküman geliştirme aşamasının hedefleri hakkında bilgilendirmek için Bokeh Slack'te aktif olun
  • Belge geliştirme aşaması planını daha da iyileş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 ait dokümanları denetlemeye ve düzenlemeye başlayın
  • Stil yönergeleri taslağını oluşturmaya başlama

2. Hafta, 21.09-27.09:

  • Stil yönergeleri üzerinde çalışmaya devam edin
  • Anlatıma ilişkin belgeleri düzenlemeye devam edin
  • Belgelerin açılış sayfasını gözden geçirmeye başlama

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ına belge kalitesi kontrolü araçlarını entegre etme konusunda Bokeh çekirdek ekibiyle görüşme

5. Hafta, 10.10 - 18.10:

  • Stil yönergelerini, anlatım belgelerinde yapılan iyileştirmeleri ve PR/CI iş akışlarını tartışmak için Slack'te Bokeh'ye katkıda bulunanlarla soru-cevap oturumu oluşturun
  • OpenGraph meta verileri için mevcut kavram kanıtlama kanıtımı dağıtılabilir bir Sphinx uzantısına dönüştürmeye başla.
  • Bokeh'e katkıda bulunanlarla yapılan Soru-Cevap oturumundaki geri bildirimlere göre stil kurallarını gözden geçirin

6. Hafta, 10 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 Ekim - 01 Ekim:

  • Sphinx 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.2008:

  • Sphinx uzantısını dağıtın ve iyileştirilmiş anlatım 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
  • Stil yönergeleri ile PR ve CI iş akışı eklemelerini içerecek şekilde Geliştirici Kılavuzu'nu güncelleyin ve yayınlayın

10. Hafta, 16.11 - 22.11:

  • Kalan görevleri tamamlayın

11. Hafta, 23 Kasım - 29 Kasım:

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

Projeyi kesinleştirme aşaması

12. Hafta, 30 Kasım - 12.05

  • Proje raporunu kesinleştirme ve gönderme

13. Hafta, 12.03 - 10.12.2010:

  • Proje değerlendirmesini sonuçlandırıp gönderin

Google Dokümanlar Sezonu bittikten sonra:

  • Bokeh'nin geliştirilmesinde yer almayı ve Bokeh belgeleri ü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, gazetecileri düşünerek Bokeh hakkında yazabilir veya gazetecilik ortamında Bokeh kullanımı hakkında konferans konuşmaları düzenleyebilirsiniz.

6. Kendim hakkında

Ben aslen gazeteciyim. TV, internet ve radyo haberleri alanında çalıştım. Televizyon haberleri ve dijital haberlerde baş editör ve muhabir olarak çalışmak bana yazma ve düzenleme alanlarında yıllarca deneyim kazandı. Aynı zamanda dijital dönüşüm ve otomasyonu teşvik eden birkaç projede çalıştım. Dijital araçları 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 ile teknoloji arasındaki kesişim her zaman ilgimi çekmiştir. 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 yapmayı başardım. Kodlamayı öğrenmek, haber merkezi iş akışları için dijital araçlar geliştirmek üzere yazılım mühendisleriyle aktif olarak birlikte ç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 kaynak projelerde daha çok yer almaya odaklanıyorum (örnekler için aşağıya bakın). Teknik yazı yazma çalışmalarımı Google'ın geliştirici belgeleri 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ıma dayalı dokümanlar, doküman dizeleri ve yazı ipuçları hazırlıyorum.

Şu anda serbest olarak çalışıyorum. Programım belge geliştirme aşamasında Bokeh’nin 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 memnunum.

7. Son açık kaynak belge örnekleri

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

  • PyPresseportal: Py Presseportal, basıneportal.de web sitesinin API'si için bir Python sarmalayıcıdır. Presseportal.de, Almanya'daki basın bültenlerinin ve yatırımcı ilişkileri duyurularının en büyük dağıtımcılarından biridir. Örneğin, neredeyse tüm polis ve itfaiyeler basın bildirilerini dağıtmak için bu hizmeti kullanır. API'yi gazeteci olarak yıllarca 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.