VLC 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:
VLC
Teknik yazar:
Abhishek Pratap Singh
Projenin adı:
VLC kullanıcı dokümanlarını modernize etmeye devam etme
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

BELGELERİN MEVCUT DURUMU

VLC Kullanıcı Belgeleri modernleştirilme ve güncellenme sürecinde. Wiki tabanlı eski dokümanlardan[1] ReadTheDocs'da barındırılan Sphinx tarafından oluşturulan modern kullanıcı dokümanlarına[2] geçiş süreci devam ediyor.

HEDEF KİTLE

Hedef kitle hem sıradan bir medya oynatıcıdan daha fazlasını isteyen meraklı kullanıcılar hem de kolay bir referans rehberi olarak geliştiricilere yardımcı olacak. Bu nedenle, son kullanıcının seçim özgürlüğü olması için hem GUI tabanlı talimatları (ilgili durumlarda resimlerle birlikte) hem de CLI tabanlı yöntemleri (kod snippet'leriyle birlikte) eklemeyi planlıyorum.

Dokümanların dilinin (özellikle GUI bölümünün), işletim bilgisayarlarını çok az kullanan bir kişinin kılavuzu anlayabileceği ve uygulayabileceği kadar sadeleştirilmesi gerektiğine inanıyorum. Diğer yandan, kodlayıcıların ilgisini kaybetmesine neden olacak kadar uzun veya açıklayıcı (özellikle CLI bölümü) olmamalıdır.

Sayfanın başında ön koşullardan bahsederek veya konuyu bilenlerin atlayabileceği isteğe bağlı bölümler ekleyerek doğru dengeyi sağlayabilirsiniz.

Çeviri oluşturmak için hedef kitle, İngilizceyi ve çevirecekleri dili iyi bilen VLC geliştiricileri/kullanıcılarıdır.

ARAÇLAR

Yeni dokümanlar Sphinx tarafından geliştiriliyor ve ReadTheDocuments üzerinde barındırılıyor, sürüm denetim sistemi ise GitLab'de kullanılıyor. Git ve GitHub'ı kullanma konusunda geçmişte edindiğim deneyimler, GitLab'ı öğrenmeme yardımcı oldu. Ancak bazı farklı özelliklerin öğrenilmesi biraz zaman aldı.

Sphinx'e gelince, açık kaynak meraklıları arasında yer alan bir arkadaşım, birçok kuruluşun dokümanlarını oluşturmak için Sphinx'i kullandığını (Kullanıcı Kılavuzu[3] ve API dokümanlarını[4] oluşturmak için Sphinx'i kullanan Blender'ın da bu örnekler arasında yer aldığını) belirttiğinde bu araç hakkında bilgi edinmiştim.

Sürüm oluşturma ve teknik dokümanları barındırma için iyi bir araç olan ReadTheDocs'u biraz tanıyordum. Bu nedenle, VLC belgelerini çok fazla sorun yaşamadan oluşturabildim ve kullanılan biçimlendirme olan reStructured Text ile aşina oldum.

VLC, i18n ve l10n'u uygulamak için çevirilerde Babel'i kullanarak .po dosyaları oluşturur. Şu anda Babel iş akışına ve Sphinx'i kullanarak .mo dosyalarının nasıl oluşturulacağına alışıyorum.

Bağlanma sürecini, yukarıda belirtilen araçların inceliklerini daha iyi öğrenmek için kullanmayı planlıyorum.

TESLİM EDİLECEK ÜRÜNLER VE HAFTALIK TAKVİM

2019 projesi kapsamında Kurulum, Arayüz, Ses, Video, Oynatma vb. (temel işlevlerin çoğu) bölümleri zaten ele alınmıştır. Bu nedenle, 2020 projesi için kullanıcı dokümanının ileri seviye kullanım bölümünü güncellemek ve üzerinde çalışmak istiyorum.

1. ÜRÜN [1.-2. Hafta]: 7. maddede [5] belirtildiği gibi kod dönüştürme dokümanlarını güncelleyin.

  • Kod dönüştürme
  • Birden fazla videoyu kod dönüştürme
  • Logo ekle
  • Videoları birleştirme
  • Ses ayıklama ve bir dosyadan ses ayıklama
  • DVD'den kopyalama

2. ÜRÜN [3.-4. Hafta]: Firefox 77, Chrome 83 ve Edge 83'te test ederken VLC'yi web eklentisi olarak kullanma[6] güncellemesi.

  • Video içeren web sayfaları oluşturma
  • Etiket özelliklerini yerleştirme
  • JavaScript API açıklaması

YAYINLANABİLİR 3 [5. Hafta]: Komut Satırı Arayüzü[7] komutlarını test edin ve uygun şekilde güncelleyin.

  • Akışlar
  • Modül seçimi
  • Öğeye Özel Seçenekler
  • Filtreler

6. Hafta: Yukarıdaki üç teslimat için Tampon Haftası.

4. ÜRÜN [7. ve 8. Hafta]: Çevirilere hazırlanın. Güncellemenin yanı sıra diğer dillere çeviri için de hazırlayacağım. Bu önemlidir, çünkü çeviriden sonra İngilizce bilgisi olmayan kullanıcılar dokümanları okuyabilecektir (ve bir yandan da VLC'nin Dünya Dominesi'ne ulaşmaya bir adım daha yaklaşacağını unutmayın[8]).

Teklifin Araçlar bölümünde belirtildiği gibi, VLC şu anda çeviriler için .po dosyaları oluşturmak üzere Babel'i kullanıyor. Kullanıcı/gönüllü için şu işlemleri belgeleyeceğim:

  • Temel dokümanları yerel olarak indirip derleyin.
  • Gerekli dosyaları oluşturmak için Babel'i kullanın.
  • Dizeler için çevirileri girin.
  • Çevrilen dokümanları Sphinx kullanarak oluşturma.
  • Değişiklikleri kaydedin.

5. ÜRÜN [9.-10. Hafta]: Modül dokümanlarına hazırlanın. Mentörlerle görüştüğümüz gibi, modül dokümanlarını iki bölüm halinde hazırlamayı planlıyorum.

Bölüm 1: Kod tabanındaki geçerli seçenekleri arayan ve ilgili wiki sayfalarından tek satırlık kullanımlarını (ve varsayılan değerlerini) ayıklayan bir komut dosyası aracılığıyla modüllerin yakınında dosyalar oluşturma. Bu, temel bir taslak görevi görür.

Bölüm - II: Belirli bir platform için tüm modülleri+eklentileri+seçenekleri birbirine bağlayan platforma özgü bir yapı oluşturma (Windows ve zaman uygunsa Fedora için de).

Dosyaları modüllerin yakınında oluşturmak, dokümanların kaynak koduna yakın olmasını sağlar. Aşağıdan yukarıdan bir yaklaşım kullanılarak, ana Modül Dokümanları, Bölüm - I'deki dosyaların birleştirilmesiyle ve referans olarak Bölüm - II'de oluşturulan yapı kullanılarak oluşturulacaktır.

Otomasyon aracılığıyla oluşturulan dosyaların incelenmesi gerekir ancak öncelikli olarak işlevsel bir çerçeve oluşturmak gerekir. Bu işlem tamamlandıktan sonra, zamana bağlı olarak seçenekleri doğrulamak için dosyaları inceleyeceğim. Kullanıma sunulduğunda geliştiriciler ve bakım uzmanları da alakalı kullanım alanları ekleyerek katkıda bulunabileceğinden çerçeveye öncelik verilmektedir.

BONUS ÜRÜN [11. Hafta]: 4.0 sürümüne hazırlanın. Projenin programa uygun şekilde ilerlemesi durumunda bonus bir teslimat önermek isterim. Mentorlarla görüşüldüğü gibi, 4.0 sürümüne hazırlanmak için 3.0 sürümü için kararlı ve neredeyse eksiksiz bir dokümana sahip olmanız gerekir.

Bu nedenle, bahsedilen yöntemleri doğrulamak ve güncellemek için aşağıdaki bölümlerin tamamlanmış dokümanlarını inceleyeceğim:

  • Temel Kullanım: Medya, Oynatma, Ses, Video, Altyazılar, Kısayol Tuşları, Kayıtlar, Ayarlar, İpuçları ve Püf Noktaları.
  • Gelişmiş Kullanım: Oynatıcı, Arayüz, Kod Dönüştürme, Akış, Olağandışı Durumlar.
  • Eklentiler: Uzantılar, Görünümler.

12. Hafta: Yukarıdaki üç teslimat için ara hafta + Nihai Raporlar.

NEDEN BU PROJE İÇİN UYGUN KİŞİYİM?

Teknoloji meraklısı olarak, yazılım kullanma/test etme konusunda deneyime sahibim ve zaman zaman, yazılım tabanlarından bir anlam çıkarmaya çalışıyorum. Açık kaynaklı bir kuruluşun kod tabanını anlamaya çalışırken dokümanların önemini ilk kez fark ettim. Ayrıca, müzik tutkunu biri olarak VLC ile ilgili birçok deneyimim var :)

Bunun dışında, hayatım boyunca araştırmacı ve yazar oldum. Bir şeyler yazmadığım sürece gerçekten anlamam mümkün oluyor. Bu alışkanlık beni not almakta ve belgelemekte verimli bir kişi oldu.

Bu iki alışkanlığın kesişimi, teknik dokümanlar için doğru kişi olmamı sağlıyor. Teknik yönleri anlayabiliyor ve bulgularımı/süreçlerimi kullanıcıların anlayabileceği bir şekilde belgeleyebiliyorum.

Bağlantılar: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35