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:
- VLC
- Teknik yazar:
- Abhishek Pratap Singh
- Projenin adı:
- VLC kullanıcı belgelerinin modernizasyonuna devam et
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
BELGELERİN MEVCUT DURUMU
VLC Kullanıcı Belgeleri, modernleştirilme ve güncellenme aşamasındadır. Wiki tabanlı eski belgelerden[1] ReadTheDokümanlar'da barındırılan sfenks tarafından oluşturulmuş modern kullanıcı dokümanlarına[2] geçiş süreci devam etmektedir.
HEDEF KİTLE
Hedef kitle, hem sıradan bir medya oynatıcının ötesinde VLC medya oynatıcısının özelliklerini keşfetmek isteyen meraklı bir kullanıcı hem de bir ölçüde, kolay başvuru kılavuzu işlevi gören geliştiricilere yardımcı olacaktır. Bu nedenle, son kullanıcının seçme özgürlüğüne sahip olması için hem GUI tabanlı talimatları (uygun durumlarda resimlerle birlikte) hem de KSA tabanlı yöntemleri (kod snippet'leriyle birlikte) eklemeyi planlıyorum.
Dokümanların dilinin (özellikle de GUI bölümünün) yönergelerin, işletim bilgisayarları ile belirli bir düzeyde iletişim kuran bir kişinin anlayabileceği ve uygulayabileceği şekilde sadeleştirilmesi gerektiğini düşünüyorum. Bununla birlikte, kodlayıcıların ilgisini kaybetmesine neden olacak çok uzun veya açıklayıcı (özellikle KSA bölümü) olmamalıdır.
Sayfanın başında ön koşullardan bahsederek veya deneyimli kişilerin atlayabileceği isteğe bağlı bölümlerden bahsederek doğru dengeyi kurabilirsiniz.
Çeviri oluşturma konusunda hedef kitle, İngilizceyi ve çeviri yapacakları dili iyi bilen VLC geliştiricileri/kullanıcılarıdır.
ARAÇLAR
Yeni dokümanlar Sphinx tarafından derleniyor ve ReadTheDokümanlar'da barındırılıyor. Sürüm kontrol sistemi ise GitLab'de uygulanmaktadır. GitLab'i daha önce kullanma konusunda biraz tecrübe yaşadım ve bu durum GitLab'i öğrenmeme yardımcı oldu. Ancak bazı farklı özellikleri öğrenmesi biraz zaman alıyordu.
Sphinx ile ilgili olarak, açık kaynak meraklısı bir arkadaşım kaç kuruluşun kendi belgelerini oluşturmak için bu araçtan yararlandığını söylediğinde bunu okumuştum (Kullanıcı Kılavuzu[3] ve API belgelerini oluşturmak için Sphinx'i kullanan dikkate değer Blender örneğiyle birlikte).
Sürüm oluşturma ve teknik belgeleri barındırma konusunda iyi bir araç olan ReadTheDokümanlar'ı biraz biliyordum. Bu nedenle, çok sorun yaşamadan VLC dokümanlarını oluşturabildim ve kullanılan biçimlendirme biçimi olan reStructured Text hakkında bilgi sahibiyim.
VLC, çevirilerde i18n ve l10n'yi uygulamak için .po dosyaları oluşturmak üzere Babel'i kullanır. Şu anda, Babel iş akışı ve Sfenks'i kullanarak .mo dosyalarının nasıl oluşturulacağı konusunda bilgi sahibiyim.
Bu bağ dönemini, yukarıda bahsedilen araçların inceliklerini daha iyi tanımak için kullanmayı düşünüyorum.
YAYINLANABİLİR REKLAMLAR VE HAFTALIK ZAMAN ÇİZELGESİ
2019 projesi kapsamında Kurulum, Arayüz, Ses, Video, Oynatma vb. bölümlerin (temel işlevlerin çoğu) nelerden oluştuğunu ele aldık. Bu nedenle, 2020 projesi için kullanıcı dokümanlarının gelişmiş kullanım bölümünü güncellemek ve üzerinde çalışmak istiyorum.
TESLİM EDİLEBİLİR 1 [1-2. Hafta]: #7[5]'te belirtildiği gibi, Kod Dönüştürme Belgelerini güncelleyin.
- Kod dönüştürme
- Birden Çok Videonun Kodunu Dönüştürme
- Logo ekle
- Videoları birleştirme
- Dosyadan Sesi Çıkar ve Sesi çıkar
- DVD çekme
DELIVERABLE 2 [3-4. Hafta]: Firefox 77, Chrome 83 ve Edge 83'te test ederken VLC'yi web eklentisi olarak kullanma[6] güncelleme.
- Video içeren web sayfaları oluşturma
- Yerleştirme etiketi özellikleri
- JavaScript API açıklaması
DELIVERABLE 3 [5. Hafta]: Komut Satırı Arayüzü[7] komutlarını test edip uygun şekilde güncelleyin.
- dinleme
- Modül seçimi
- Öğeye Özgü Seçenekler
- Filtreler
6. hafta: Yukarıdaki üç teslimat için Tampon Haftası.
YAYINLANABİLİR 4 [7-8. Hafta]: Çeviri için hazırlanın. Güncelleme dışında diğer dillere çeviri için de hazırlayacağım. Çeviriden sonra, İngilizce arka planı olmayan kullanıcılar dokümanları okuyabileceği için bu önemlidir (ve VLC, çeviriden sonra Dünya Hakimiyeti'ne bir adım daha yaklaşacaktır[8]).
Teklifin Araçlar bölümünde belirtildiği gibi, VLC şu anda çeviriler için .po dosyaları oluşturmak için Babel'i kullanmaktadır. Bir kullanıcı/gönüllü için süreci aşağıdaki amaçlarla belgeleyeceğim:
- Temel belgeleri indirin ve yerel olarak oluşturun.
- Gerekli dosyaları oluşturmak için Babel'i kullanın.
- Dizeler için Çeviriler girin.
- Sfenks'i kullanarak çevrilmiş belgeleri oluşturma.
- Değişiklikleri uygulayın.
YAYINLANABİLİR 5 [9-10. Hafta]: Modül belgeleri için hazırlanın. Mentorlarla da konuştuğum gibi, modül belgeleri için iki bölüm hazırlamayı planlıyorum.
Bölüm - I: Kod tabanından geçerli seçenekleri arayan ve ilgili wiki sayfalarından tek satırlık kullanımları (ve varsayılan değerleri) çıkaran bir komut dosyası aracılığıyla modüllerin yakınında dosyalar oluşturma. Bu, temel bir taslak işlevi görür.
Bölüm - II: Belirli bir platforma ait tüm modül+eklentileri+seçenekleri birbirine bağlayan, platforma özgü bir yapı oluşturma (Windows ve zaman sıkıntısı varsa Fedora için de).
Modüllerin yakınında dosya oluşturmak, belgelerin kaynak koduna yakın olmasını sağlar. Aşağıdan yukarıya bir yaklaşım kullanılarak, ana Modül Dokümanları 1. Bölüm'de oluşturulan dosyaların birleştirilmesi ve II. Bölüm'de yapılan yapının referans olarak kullanılmasıyla oluşturulur.
Otomasyonla oluşturulan dosyaların incelenmesi gerekir ancak ilk öncelik işlevsel bir çerçeve oluşturmaktır. Bu adım tamamlandıktan sonra, uygun zamanda seçenekleri doğrulamak için dosyaları inceleyeceğiz. Kullanıma sunulduğunda çerçeveye öncelik verilmektedir. Geliştiriciler ve geliştiriciler de alakalı kullanım alanları ekleyerek katkıda bulunmaya başlayabilirler.
BONUS DELIVERABLE [11. Hafta]: 4.0 sürümüne hazırlanın. Projenin zaman çizelgesine uygun şekilde ilerlemesi durumunda, bonus teslimat önermek istiyorum. Mentorlarla da konuştuğumuz gibi, 4.0 sürümüne hazırlanmak için 3.0 sürümü için belgelerin stabil ve neredeyse eksiksiz olması gerekir.
Bu nedenle, bahsedilen yöntemleri doğrulamak ve güncellemek için aşağıdaki bölümlerde yer alan zaten tamamlanmış belgeleri gözden geçirmem gerekir:
- 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, Dış Görünümler.
12. Hafta: Yukarıdaki üç teslimat + Nihai Raporlar için Tampon Haftası.
BU PROJE İÇİN NEDEN DOĞRU KİŞİSİM?
Teknoloji meraklısı olarak yazılımları kullanma/test etme konusunda deneyimliyim ve bazen de kod tabanlarından anlam çıkarmaya çalışıyorum. Aslında, belgelemenin önemini ilk kez, açık kaynak bir kuruluşun kod tabanını anlamaya çalışırken fark ettim. Ayrıca, bir müzik tutkunu olarak VLC'yi kullanma konusunda çok deneyimim var :)
Bunun dışında, hayatım boyunca araştırmacı ve yazar oldum. Bir şeyler yazmadığım sürece onu hiçbir zaman tam olarak anlamam ve bu alışkanlık beni verimli bir not tutma ve belgeleme becerisi haline getirdi.
Bu iki alışkanlığın kesişimi, beni teknik belgeler için doğru aday yapan şey. Bulgularımı/süreçlerimi kullanıcıların anlayacağı şekilde belgelemenin yanı sıra teknik yönleri de bulabiliyorum.
Bağlantılar: [1] https://wiki.videolan.org/Documentation:User_Guide/Eklentileri