Wikimedia Foundation 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:
The Wikimedia Foundation
Teknik yazar:
Pavithra Eswaramoorthy
Proje adı:
Wikimedia'nın teknik belge uzmanları ve videografları için dokümanları iyileştirme
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

1. Hakkımda

Açık kaynaklı yazılımlarla birkaç ay önce tanıştım ve hemen ardından sınırsız kapsamı karşısında bunalmaya başladım. Milyarlarca proje arasından yolumu bulmaya çalışırken Google Summer of Code ve Outreachy gibi açık kaynak girişimleri hakkında bilgi edindim. Google Dokümanlar Sezonu ilgimi çekti ve Wikimedia Foundation'ın proje fikirleri merak uyandırdı. Bu nedenle daha fazla araştırma yapmaya başladım.

Şimdiye kadarki yolculuğum hem heyecan verici hem de kafa karıştırıcıydı. "Bekle, ne?", "Aha, anladım" ve "Bunu yorumlamalı mıyım?" gibi sorularla dolu bir yolculuktu. Wikimedia topluluğu her adımda destek oldu. Sayfaları düzenlemekten uzantı oluşturmaya kadar her gün yeni bir şeyler öğrendim.

Beklendiği gibi, başvuru süreci açık kaynak topluluğuna giriş kapısı görevi gördü. Bu öneri, başlangıç seviyesindeki kendi deneyimlerimden esinlenmiştir.

2. Proje

2.1. Dış çizgi

Bu projenin amacı, Wikimedia'da teknik yazarlar ve potansiyel videograflar için dokümanları iyileştirmektir. Teknik dokümanlar için kapsamlı bir yönergeler grubu, genel dokümanların iyileştirilmesine yardımcı olur. Ekran kaydı oluşturmayla ilgili referanslar ise yazılım özelliklerinin etkili bir şekilde gösterilmesini sağlar. Bu alanlarda mevcut dokümanlar, hem yeni hem de deneyimli katkıda bulunanları daha iyi desteklemek için genişletilebilir. Yararlı kaynaklardan oluşan bu ağı geliştirmek için kademeli bir yaklaşım benimsenecektir.

2.2. Teslim edilecek materyaller

  • T197006 [https://phabricator.wikimedia.org/T197006] - Wikimedia'nın belgeselcileri için dokümanları iyileştirme:

    • Dokümanlar/Stil kılavuzuna ipuçları ve örnekler ekleyin. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Teknik doküman şablonları ve önerilerinde belirli türler için MediaWiki'ye özel bilgiler ekleyin: Kullanıcı kılavuzları, "Nasıl Yapılır?" kılavuzları, hızlı başlangıç kılavuzları, sürüm notları ve README'ler. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Teknik doküman önceliklendirme yönergelerini test edin ve iyileştirin. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Farklı doküman türleri için içerik toplama stratejisi tasarlayın.
    • MediaWiki belgeleri için bir iletişim ve ortak çalışma stratejisi tasarlayın.
    • Yazarların yayınlamadan önce dokümanlarını inceleyebileceği bir yapılacaklar listesi oluşturun.
    • Yeni teknik yazarlar için doküman yapısını genişletin. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Hackathon'lara uygun teknik doküman görevlerinin listesini oluşturun. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Teknik yazarlar için faydalı kaynaklara yönlendiren bir merkez oluşturun.

  • MediaWiki videografları için dokümanları iyileştirin:

    • Genel ekran kaydı oluşturma ile ilgili kısa bir kullanıcı kılavuzu oluşturun.
    • Rehberler ve eğitici içerikler için MediaWiki'ye özel ekran kaydı şablonları tasarlayın.

  • T214522 [https://phabricator.wikimedia.org/T214522]- "Phabricator'a Giriş" konulu bir ekran kaydı oluşturma.

2.3. Esneme Hedefi

  • İçeriği yeniden kontrol edin ve WikiProject ekran kaydı dokümanlarını güncelleyin. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentorlar

Zulip, mentorlarımla iletişim kuracağım birincil yöntem olacak. Toplulukla yapılacak tartışmalar için Wikimedia'nın IRC kanalları ve e-postaları kullanılacaktır. Belirli görevlerle ilgili tartışmalar, Phabricator görevlerinin yorumlar bölümünde gerçekleşir.

4. Tartışma

Bu proje genel olarak iki aşamaya ayrılır:

(i) Wikimedia teknik yazarları için mevcut kaynakları iyileştirme.

(ii) Potansiyel kameramanlar için faydalı şablonlar oluşturun.

(i) Wikimedia'nın teknik yazarları için mevcut kaynakları iyileştirme.

Geçmişte, MediaWiki'nin belgelerini çeşitli başarı oranlarıyla iyileştirmek için birçok girişimde bulunuldu. Bunlardan bazıları şunlardır:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Bu çalışmalardan, teknik yazarlara yönelik daha iyi bir kaynak setinin, oluşturdukları belgeler üzerinde doğrudan bir etkisi olacağını anlayabiliriz.

Aşağıda, Outreachy 2018 stajyeri Anna e só'nun https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/ adresindeki iki haftalık raporundan bir snippet verilmiştir:

"MediaWiki'nin stil kılavuzu mükemmel değildir, özellikle de en iyi olarak değerlendirdiği uygulamaları vurgulamadan harici referanslara çok fazla dayandığından. Maalesef bu sorun yalnızca MediaWiki ile sınırlı değil, Çeviri en iyi uygulamaları gibi diğer belgelerde de ortaya çıkıyor. Yazarlar, işlerini yapacak iyi ve güvenilir kaynaklara sahip olmadığından hedef kitle ve uygun bir yazı stili belirlemekte zorluk yaşarlar. Özellikle yeni kullanıcılar, yeni kavramları ve süreçleri anlama konusunda sorun yaşayabilir."

T197006 [https://phabricator.wikimedia.org/T197006], teknik yazım dokümanlarında iyileştirme yapılması gereken belirli alanlara da ışık tutuyor. Başlangıç noktası olarak Documentation/Style_guide'ı kullanmanız gerekiyor.

Daha iyi bir stil kılavuzu oluşturduktan sonra, teknik yazarlara teknik yazmanın farklı aşamalarında rehberlik edecek bir sonraki belge grubunu planlıyoruz. Dokümanlar, yeni başlayanlara uygun olmalı ve aynı zamanda yazarların tekrar başvurabileceği tüm bilgileri sağlamalıdır.

Hazırlık aşaması, belgenin temelini oluşturduğu için belki de en önemli aşamadır. Teknik yazarları bu aşamada desteklemek için alakalı bilgileri toplamanın bazı etkili yollarını ve bu bilgileri şablonlar kullanarak yapılandırmayla ilgili ipuçlarını açıklayan referans dokümanları geliştirilir.

Ardından yazma aşaması gelir. Yazarlara, çıtayı otomatik olarak yüksek tutmak için iyi çalışmaların örnekleri sunulur. Ayrıca, her dokümanın uyması gereken temel ölçütlerden oluşan bir yapılacaklar listesi oluşturulur. Bu liste, yazarların dokümanlarını yayınlamadan önce incelemelerine yardımcı olur.

Bu belgelere rağmen yeni teknik yazarların ek yardıma ihtiyacı olacak ve onlara bu yardımı sağlamamız gerekiyor. Yeni teknik yazarlara yönelik kılavuz geliştirildi ve hackathon'lara uygun görevlerin listesi zorluk düzeyine göre düzenlendi.

Son olarak, belgelerin yönetilmesi ve sürdürülmesi sürecini anlamaya yönelik bir belge: "Teknik belge önceliklendirme". Test edilmiş ve iyileştirilmiştir.

Bu aşamanın sonunda, doküman stil kılavuzunu destekleyen teknik yazma kılavuzları, kaynaklar, örnekler, öneriler ve şablonlardan oluşan bir merkez oluşturulacak.

(ii) Potansiyel kameramanlar için faydalı şablonlar oluşturun.

"Grafik içeren her şeyi öğrenmenin en zor yollarından biri, düz metin okumak. Kılavuzunuzda yazılımın yanlış sürümü belirtilirse ne olacağını da düşünün. Yalnızca metin içeren kılavuzlarda, genellikle normalde kullandığımız tüm ipuçlarından yoksun olduğumuz için uygulamadaki menüler ve kelimeler değiştiğinde bir dizi işlemi yeniden oluşturmak imkansız hale gelir.

Öğrenmenin en iyi yolu, yanınızda bir uzmanın olmasıdır. Ekran video kayıtları, statik grafikler arasında yer alır ve bir uzmana yakın zamanda hazırlanır. Dostça bir sesle hareketli bir görsel demo alırız. Ekranda metin ek açıklamaları ve animasyonlar da olabilir. Ekran kayıtlarının uzmanlara kıyasla avantajı, her gün her saat istenildiği zaman yeniden oynatılabilmesidir.

Ayrıca, ekran kaydı videolarına çevrilmiş altyazılar ekleyerek videonun orijinal dilini bilmeyen kullanıcıların da videoyu izleyebilmesini sağlayabilir veya ses parçasını alternatif dillerle değiştirebiliriz."

"The Screencasting Handbook" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] adlı kitaptan alınan yukarıdaki snippet'te Ian Ozsvald, ekran kayıtlarının önemini açıklıyor. Bu, özellikle MediaWiki geliştirme ortamını ayarlama, uzantı yazma, Gerrit'i kullanma ve daha fazlasıyla ilgili eğitimler için yararlı olabilir.

Dokümanlar için sunulan şablonlara benzer şekilde, ekran video kaydı için standart bir şablona sahip olmak tutarlılığı ve böylece izleyicinin deneyimini iyileştirir. Ayrıca, video çekmeye yeni başlayanlara bir çerçeve sunar. Bu nedenle, kısa bir kullanıcı kılavuzu ve ardından tanıtım ve eğitim videoları oluşturmak için şablonlar geliştirilir. Dokümanlar, ele alınacak kavramların derinliği hakkında ipuçları ve MediaWiki için birkaç ekran kaydı fikri içerir.

Yukarıdaki şablonu test etmenin ve ek hedefe hazırlanmanın en iyi yolu, araçları ve şablonları kullanarak ekran kaydı oluşturmaktır. Bu nedenle, Phabricator'un temel özelliklerini kapsayan bir "Phabricator'a Giriş" ekran kaydı oluşturulur. Bu süreç ayrıca tartışılması gereken alanları da vurgular.

Son olarak, Wikimedia'nın videograferleri için merkezi referans kaynağı olan WikiProject Screencast incelendi ve güncellendi.

5. Kesinleşmemiş zaman çizelgesi

Toplulukla kaynaşma dönemi (1 Ağustos - 1 Eylül)

  • Projeyi mentorlarımla ayrıntılı olarak analiz ettim.

  • Şunları tartışın:

    • Görevlerin ne sıklıkta incelenmesi gerektiği.
    • Programları paylaşın ve haftalık/günlük iş akışına karar verin.
    • Kullanılabilen araçlar ve kaynaklar.
    • İki haftada bir ve günlük proje raporları.

  • Phabricator'da gerekli görevleri ve alt görevleri oluşturun.

  • Doküman geliştirme aşamasında kişisel taahhütleri telafi etmek için taslaklar oluşturun.

1. Hafta (2 - 8 Eylül)

  • Documentation/Style_guide'ı iyileştirin:

    • Birincil odak noktasını, MediaWiki'deki en iyi uygulamaları ve standartları göstermeye kaydırın.
    • İyi çalışmalara örnekler ekleyin ve ilişkili sayfaların görünürlüğünü artırın.

  • Yeni teknik yazarlar için kılavuzu iyileştirin:

    • Belge yapısının kapsamını genişletin.

2. Hafta (9 - 15 Eylül)

  • Teknik dokümanlara öncelik verme konusunda çalışma:

    • Dokümanlar iş panosunu değerlendirin; iyi görev açıklamaları ve önceliklendirmeye dair örnekler bulun.
    • Eğilimleri inceleyin ve sık karşılaşılan zorlukları not edin.
    • Önceliklendirme standartlarını belgelemek için bilgileri ve örnekleri kullanın.

3. Hafta (16 - 22 Eylül)

  • Teknik yazarlar için aşağıdaki ek dokümanları oluşturun:

    • Teknik dokümanları yayınlamadan önce incelemenize yardımcı olacak bir yapılacaklar listesi.
    • Farklı doküman türleri için etkili bir şekilde içerik toplama yöntemleri.

4. Hafta (23 - 29 Eylül)

  • Teknik doküman şablonlarına ve önerilerine en yaygın MediaWiki türlerinde yazma hakkında bilgi ekleyin:

    • Kullanıcı kılavuzları, hızlı başlangıç kılavuzları, README'ler, sürüm notları ve "Nasıl yapılır?" kılavuzları yazmak için MediaWiki'deki en iyi uygulamaları belgeleyin.

  • Teknik iletişimin olgunluğunu artırmak için talimatlar ekleyin. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

5. Hafta (30 Eylül - 6 Ekim)

  • Yeni ortak çalışanların ilk katılımıyla ilgili dokümanları iyileştirin:

    • Sayfayı güncelleyin: Hackathon'lar için teknik doküman görevleri. (Yapılacaklar: Proje dönemi boyunca bu sayfaya uygun görevler ekleyin)

  • Teknik yazar merkezi oluşturma

    • Yararlı sayfaların ve kaynakların bağlantılarını içeren bir açılış sayfası oluşturun.
    • Yeni ve mevcut sayfalar arasında daha kolay gezinmek için gerekli bağlantıları ekleyin.

6. Hafta (7 - 13 Ekim)

  • MediaWiki için video oluşturma hakkında aşağıdaki dokümanları oluşturun:

    • Ekran Kaydı Projesi'ne yönlendiren "genel ekran kaydı oluşturma" konulu kısa bir kullanıcı kılavuzu.
    • Şablonlar: Bir yazılımın/aracı kullanmayla ilgili adım adım açıklamalı kılavuzlar; Yeni araçlar geliştirmeyle ilgili eğitici içerikler.

  • MediaWiki için ekran kaydı fikirleri listesi oluşturun.

7. Hafta (14-20 Ekim)

  • "Phabricator'a Giriş" videosu üzerinde çalışın:

    • Bir komut dosyası taslağı oluşturmak için şablonu (önceki hafta oluşturulan) kullanın.
    • Şablonun verimliliğini tahmin edin ve gerekirse şablonu iyileştirin.
    • Geri bildirim alın ve taslağı tamamlayın.

8. Hafta (21 - 27 Ekim)

  • "Introduction to Phabricator" başlıklı videoyu yayınlayın:

    • Yazılımı seçin ve yükleyin.
    • Ortamı ayarlayın ve ekran kaydı oluşturun.
    • Karşılaşılan sorunları ve çözümleri not edin.

9. Hafta (28 Ekim - 3 Kasım)

  • Ekran kaydı projesiyle ilgili dokümanları iyileştirmeye çalışın:

    • Yapıyı inceleyin ve değişiklik yapılması gerekip gerekmediğini tartışın.
    • Söz konusu yazılımları inceleyin.
    • Yazılım listesini araştırıp güncelleyin.

10. Hafta (4 - 10 Kasım)

  • Ekran Kaydı proje belgelerini iyileştirmeye devam edin:

    • Eğitimi ve komut dosyalarını değerlendirin ve geliştirin.
    • Ekran kaydı galerisini inceleyin.

11. Hafta (11 - 17 Kasım)

  • Ekran kaydı proje dokümanlarıyla ilgili çalışmaları tamamlayın:

    • Yeni videoları bulup galeriye ekleyin.
    • Gerekli yapısal değişiklikleri yapın.

12. Hafta (18 - 24 Kasım)

  • Beklemedeki görevler üzerinde çalışın.

  • Nihai raporu yazın:

    • İki haftalık/günlük raporlara göz atın ve gerekli bilgileri toplayın.
    • Rapor yapısını planlayın ve bir taslak yazın.
    • Mentörün geri bildirimlerine göre taslağı iyileştirin ve sonlandırın.

13. Hafta (25-29 Kasım)

  • Nihai raporu gönderip mentor değerlendirmesini yapmak.

6. İlerleme İzleme

Günlük ilerleme güncellemeleri, Zulip üzerinden danışmanlarıma iletilecek. Wikimedia topluluğu, Phabricator veya iki haftada bir yayınlanan proje raporları aracılığıyla ilerleme durumumu takip edebilir.

7. Diğer Taahhütler

Tam zamanlı bir üniversite öğrencisiyim ve akademik sonbahar dönemim, Dokümanlar Sezonu zaman çizelgesiyle çakışıyor. Bu nedenle, üniversite sınavları da taahhütlerim arasında.

İlk dahili sınav: 18-24 Ağustos

İkinci şirket içi sınav: 29 Eylül - 6 Ekim

Dönem sonu sınavı: 11-30 Kasım

Ayrıca, bu yılki uygun konum sayesinde 12-15 Ekim tarihleri arasında ilk herkese açık konferansım olan PyCon India'ya katılmayı planlıyorum. Yeni insanlarla tanışmak ve ilgi çekici sohbetler yapmak için harika bir fırsat olduğunu düşünüyorum.

Bu taahhütleri yönetmek için, geçici zaman çizelgesi ilgili haftalarda daha az ağırlıklı görevler içerir. Belge geliştirmeye yeterince zaman ayırabilmek için sonbahar döneminde en fazla 20 temel kredi tamamlamayı planlıyorum. (Normal bir öğrenci, sömestr başına ortalama 25 kredi tamamlar.)