VideoLAN 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:
VideoLAN
Teknik yazar:
Edidiong Anny Asikpo
Proje adı:
VLC kullanıcı belgelerini modernize etme (yeniden yazma)
Proje uzunluğu:
Standart uzunluk (3 ay)

Proje açıklaması

ABSTRACT

Kullanıcı dokümanları, son kullanıcıların bir ürünü veya hizmeti kullanmasına yardımcı olmak için tasarlanmıştır. İyi bir kullanıcı dokümanı, kullanıcıların bir yazılımı nasıl kullanacağını, özelliklerini, ipuçlarını ve püf noktalarını öğrenmesine ve yazılımı kullanırken karşılaşılan yaygın sorunları çözmesine olanak tanıdığı için çok önemlidir. Ayrıca destek maliyetini azaltır ve ürünün kurumsal kimliğinin bir parçasıdır: İyi bir kullanıcı dokümanı, ürünün ve geliştirici ekibinin sağlıklı olduğunun bir göstergesidir.

İyi bir kullanıcı dokümanları olmadan kullanıcılar yukarıdaki işlemleri etkili ve verimli bir şekilde nasıl yapacaklarını bilemeyebilir. Kullanıcı dokümanları, bir ürünün başarılı olmasında önemli bir rol oynayabilir. Bunun nedeni, mükemmel iletişimin her işletmenin veya ürünün merkezinde yer alması ve her zaman da öyle kalmasıdır. Mükemmel bir doküman, bu iletişimi alıp herkes için başarılı olabilecekleri, yönetilebilir bir çerçeveye yerleştirir.

Bu makalenin yazıldığı sırada VLC kullanıcı dokümanlarına 4.634.065 kez erişilmiş ve VLC Media Player ana web sitesinden her ay yaklaşık 23 milyon kez indirilmiştir. Bu, dünyanın dört bir yanındaki birçok kişinin VLC Media Player'ı kullandığını ve medya oynatıcının nasıl kullanılacağı konusunda rehberlik için kullanıcı dokümanlarını okumak isteyebileceğini gösterir. Bununla birlikte, VLC medya oynatıcı kullanıcı dokümanları şu anda güncelliğini yitirmiş ve eksiktir (en son 28 Ekim 2015'te değiştirilmiştir) ve VideoLAN topluluğu, son kullanıcıların VLC medya oynatıcıyı kullanırken sorunsuz bir deneyim yaşamalarını sağlamak amacıyla kullanıcı dokümanlarını iyileştirmek için bu projeyi kullanmak istemektedir.

MEVCUT DURUM

Kullanıcı dokümanları şu anda wiki sayfasında mevcuttur. Bu doküman eski, eksik, gezinmesi veya bilgi bulması zor, medya oynatıcının mevcut sürümüyle ilgili bilgileri kapsamamaktadır ve yalnızca Almanca olarak çevrilebilir. Bu da İngilizce dilini okuyamayan kişiler için büyük bir aksaklığa neden olur.

ÖNERDİĞİM KULLANICI DÖKÜMANLARI, MEVCUT DÖKÜMANLARA NEDEN İYİ BİR DEĞİŞİKLİK OLARAK GÖSTERİLİYOR?

Önerilen kullanıcı dokümanları, son kullanıcının verimliliğini, tutarlılığını ve rahatlığını iyileştirmek ve sağlamak için yapılandırılır. Yazılı kılavuzları ve ilişkili resimleri içerir. VLC medya oynatıcının her özelliğinin nasıl kullanılacağına dair talimatlar ve açıklamalar içerir. Güncel, gezinmesi kolay, anlaşılır ve en az beş ana dilde çevrilebilir olmalıdır.

Mentörler: Jean-Baptiste, Alex, Simon

ANALİZ

Jean-Baptiste ile, mevcut kullanıcı dokümanlarının iyileştirmeler için taşınacağı yeni ortam hakkında konuştuk. Sphinx ile yazılmış kaynak dosyanın Gitlab deposunu ve Read the Docs'da barındırılan ana dokümanları gösteren iki bağlantı paylaştı. Yeni dokümanların buna benzer olmasını beklediklerini söyledi. İşleyiş şeklini daha iyi anlamak için bu araçlar hakkında çok fazla araştırma yaptım.

Sfenks

Sfenx, yazılım belgeleri için sağlam ve olgun bir çözümdür. Yazarların beklediği birçok özellik içerir. Örneğin, tek kaynaktan yayınlama, dahil etme yoluyla içerik yeniden kullanma, içerik türüne ve etiketlere dayalı koşullu dahil etme, mobil cihazlarda ve masaüstünde mükemmel bir kullanıcı deneyimi sunan birden fazla gelişmiş HTML teması, sayfalar, dokümanlar ve projeler arasında referans verme, dizin ve sözlük desteği ve uluslararasılaştırma desteği. Ayrıca, biçimlendirme dili olarak reStructuredText'i kullanır ve birçok avantajı, reStructuredText'in gücü, basitliği ve dokümanları çevirme yeteneğinden gelir.

Belgeleri okuyun

Read the Docs, dokümanlarınızı oluşturma, sürüm oluşturma ve barındırma işlemlerini sizin için otomatikleştirerek yazılım dokümanlarını basitleştirir. Hiçbir zaman senkronize edilmez. Yani, ister Git, Mercurial, ister de Market veya Subversion gibi favori sürüm kontrol sisteminize her kod aktarırsanız, Read the Docs, dokümanlarınızı otomatik olarak oluşturur, böylece kodunuz ve dokümanlarınız her zaman güncel kalır. Birden fazla sürümü vardır; Read the Docs, dokümanlarınızın birden fazla sürümünü barındırabilir ve oluşturabilir. Böylece, dokümanlarınızın 1.0 ve 2.0 sürümlerine sahip olmak, sürüm kontrol sisteminizde ayrı bir dal veya etikete sahip olmak kadar kolaydır. Ücretsiz ve açık kaynak olan Read the Docs,neredeyse tüm insan ve bilgisayar dillerinde yaklaşık 100.000 büyük ve küçük açık kaynak projesinin belgelerini barındırır.

VERDICT

Sphinx inanılmaz derecede güçlü bir araçtır. Read the Docs, Sphinx dokümanları için barındırma hizmeti sunarak dokümanlarınızı tüm sürümlerde güncel tutar. Bunlar, geliştiricilerin ve teknik yazarların son kullanıcılara en uygun kullanıcı dokümanlarını oluşturmak için kullanabilecekleri harika bir araç setidir.

Sphinx, dokümanları birden fazla dile çevirme desteği içerir. Dokümanları yönetmek için kullanılacak sürüm kontrolünü destekler. Herkesin düzenleyebileceği ve doğru bilgileri ekleyebileceği mevcut wiki'nin aksine bu sürüm kontrol sistemi, ana depoya birleştirilmeden önce tüm değişikliklerin incelenmesini sağlar. Sürüm kontrolü ayrıca kullanıcıların sorun oluşturabilmesi, çekme isteklerini açabilmesi vb. sayesinde belgelerin açık kaynak katkısını da artırır. Sphinx ve Dokümanlar'ı okuma, ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs gibi diğer büyük ve toplulukların bir listesi tarafından kullanılır ve yeni VLC kullanıcı dokümanları için mükemmel bir araçtır.

Bu araçlar hakkında bilgi edinmekle kalmadım, temel bir örnek de oluşturdum. Gitlab depom için https://gitlab.com/Didicodes/demo-vlc-user-documentation adresini ziyaret edin.

ÖNERİLEN BELGELERİN YAPISI

VLC kullanıcı dokümanları için bir yapı oluşturdum. Bu yapıya https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing adresinden ulaşabilirsiniz. Bu yeni yapının uygulanmasına başlanmadan önce mentorlar tarafından onaylanması gerekir. Bu, yapının mentorlar tarafından incelendikten sonra değişebileceği anlamına gelir.

PROJE HEDEFLERİ

  • Dokümanları yeniden yapılandırın.
  • Dokümanları VLC'nin modern sürümlerine uygun olacak şekilde güncelleyin.
  • Sphinx ve ReadtheDocs'u kullanarak kullanıcı belgelerini Gitlab'a taşıyın.
  • Eski resimleri ve bilgileri kaldırın.
  • Kullanıcı dokümanlarını daha kolay anlaşılır hale getirmek için yeniden yazın.
  • Sfenks Uluslararasılaştırma'yı kullanarak çeviri için ayarlayın.
  • Kullanıcıların dokümanları okurken karşılaştıkları sorunları bildirebilmesi veya çözebilmesi için dokümanları topluluk odaklı hale getirin.

NEDEN BU PROJE?

Kod yazmanın, sorun çözmenin ve yazılım oluşturmanın tam potansiyeline ulaştığına inancım her zaman var. İnsanları kod yazma yoluyla da bu konuda aydınlatabilirsin. VideoLAN topluluğunun multimedya için ücretsiz yazılım çözümleri üretme konusunda gösterdiği çabalar beni her zaman etkilemiştir. Çocukken müzik dinlerken veya film izlerken kullandığım VLC medya oynatıcı, oldukça yüksek sesli olduğu ve birçok özellikten oluştuğu için her zaman kullandığım yazılımdı. Çocukluğumun harika geçmesine katkıda bulunan toplulukla çalışmak benim için bir onur olacak.

NEDEN BU PROJE İÇİN DOĞRU KİŞİ BENİM?

Bu proje için doğru kişi olduğumu düşünüyorum çünkü:

  • Kuruluşların dokümanlarını iyileştirme konusunda geçmiş deneyimim var ve herhangi bir sürüm kontrol sistemini kullanabilirim. Bu nedenle, Gitab'da komutları yürütmek benim için sorun olmaz. Ayrıca, insanlar için değer yaratan projeler üzerinde çalışmak beni motive ediyor.
  • Birinin bir işi mümkün olan en verimli şekilde yapmasını istiyorsanız bunu belgelemeniz gerektiğini düşünüyorum. Süreçlerinizi belgeleyerek sürece dahil olan herkes için verimlilik, tutarlılık ve gönül rahatlığı sağlarsınız.
  • VLC kullanıcılarının ihtiyaçlarını, kendim de bir VLC kullanıcısı olduğum için çok iyi biliyorum. Bu sayede dokümanları, dünya üzerindeki diğer tüm kullanıcıların ilk bakışta anlayabileceği şekilde yazabilirsiniz.