Özgür ve açık Yazılım geliştirmek için iyi uygulamalar: Belgeler

La belgeleme temel bir parçasıdır ve olmalıdır yaratıcı süreç ve planlama tüm insan faaliyetlerinin ve teknolojik alanda, özellikle de Yazılım geliştirme.

El tüm belgelerin amacı O olmalı üçüncü taraflara öğretin (kullanıcılar, yöneticiler, bakımcılar veya diğer geliştiriciler)genellikle aşina olmayanlar ürün (kod, uygulama veya sistem), nasıl yaratıldı yapısı, işleyişi ve mümkün olsa bile, yaratılış nedeni ve tasarım ve işleyiş şekli.

Ayrıca, özel durumda Özgür Yazılım dokümantasyonu çok önemlidirtam olarak garanti etmeye izin verdiği için bilgi transferi ve yetkilendirme tatmin edici bir şekilde yerine getirilmesi için gerekli 4 özgürlük onun tarafından tanıtılır, bunlar:

• 0: Programı istediğiniz gibi, herhangi bir amaçla çalıştırma özgürlüğü.
• 1: Bir programa erişme ve çalışma özgürlüğü ve kendi çıkarınız için onu değiştirme veya uyarlama özgürlüğü.
• 2: Aynı şeyleri yaymak ve / veya başkalarına yardım etmek için kopyaları paylaşma veya yeniden dağıtma özgürlüğü.
• 3: Değiştirilmiş sürümlerinizin kopyalarını üçüncü şahıslara dağıtma özgürlüğü.

İyi bir dokümantasyon, bu nedenle, oluşturulan ürünün:

• Doğru kullanılır ve daha kolay öğretilir ve öğrenilir.
• İyileştirmek veya uyarlamak için onu değiştirmek isteyenler tarafından iyice anlaşılmalıdır.
• Tüm potansiyel tanıdıklar ve yabancılar arasında daha güvenle paylaşılmalı ve karşılanmalıdır.
• Halk arasında daha iyi bir kitle olsun.

İyi uygulamalar: Belgeler

Temel bilgiler

Söz konusu Özgür Yazılım ve Açık Kaynak Geliştirme, genellikle, belgelerin ana kullanıcıları ürün tasarımıyla ilgili olanlar, olanlar veya olacaklar mı, bakımdan sorumlu aynı. İyi ya da hiç dokümantasyon olmadan, tek geçerli alternatif, doğrudan araştırmak, tasarımını ve işlevini anlamak.

Söz konusu olduğunda iyi belgeler oluşturmamak Özgür Yazılım geliştirmek, Açık Kaynak veya başka herhangi bir yazılım türü, olası alıcılarına göndermek (kullanıcılar, yöneticiler, bakımcılar veya diğer geliştiriciler) harita veya pusulasız bir ormanda bir yol bulmak için.

Her biri için iyi belgeler oluşturun Özgür Yazılım, Açık Kaynak aynı zamanda faydalıdır, çünkü belgelemenin bir maliyeti vardırYatırım doğru yapılırsa buna değer. Çünkü dünya Software hakkında hikayelerle dolu eski kodlar Neredeyse hiç kimsenin anlamadığı için çok az kişinin dokunmaya cesaret edebildiği eski veya güncel programlar, uygulamalar veya sistemler. Programcılar kod oluşturmaya ve onu doğru ve tam olarak belgelememeye odaklanır. Ve bu düzeltilmelidir.

README metin dosyalarındaki dokümantasyona ilişkin iyi uygulamalar

Söz konusu Özgür Yazılım ve Açık Kaynak, belgeler bireyler veya küçük programcı veya topluluk grupları tarafından oluşturulduğunda genellikle metin dosyalarıyla sınırlıdır. Ancak, basit bir belge kullanarak basit bir belge oluşturana kadar metin dosyası README.md (veya .txt) senin olabilir en iyi veya iyi uygulamalar, oluşturulanlar hakkında gerekli olan en eksiksiz ve ayrıntılı bilgileri üçüncü taraflara götürmek için ipuçları veya yararlı oluşturma kılavuzu.

Makalemiz için, İyi uygulamalar tarafından tasarlanan ve ifşa edilen "Geliştirme Girişimi Kodubaşlıklı bir kılavuz yayınladı del Interamerican Kalkınma Bankası, özetlenmiş bir şekilde bize bir metin dosyası README.md (veya .txt) Aşağıdaki şekilde yapılandırılmalıdır:

Önerilen README dosya yapısı

• Açıklama ve bağlam: İşlevleri, geliştirildiği bağlamı ve çözülmesine yardımcı olduğu geliştirme sorunlarını açıklamanız gereken bölüm.
• Kullanıcı Kılavuzu: Dijital aracı kullanmaya nasıl başlayacağına dair son kullanıcıya talimatların belirtilmesi gereken bölüm.
• Yükleme Rehberi: Dijital aracı yeniden kullanmak ve yapılandırmak için kurulum talimatlarının belirtilmesi gereken bölüm. Bu bölüm geliştiricilere yöneliktir.
• yazarlar Aracın ortak çalışanlarına jeneriğin verilmesi gereken bölüm.
• Alet kodu için lisans: Dijital aracı yeniden kullanmak için üçüncü şahıslara verilen izinlerin belirtilmesi gereken bölüm.
• Aracın dokümantasyonu için lisans: Oluşturulan belgelerde yer alan lisans türünün belirtilmesi gereken bölüm.

Bunlarda iyi uygulama, ayrıca README dosyası belgeleri daha eksiksiz hale getirmek için aşağıdaki bölümler:

• Nasıl katkıda bulunulur: Yeni geliştiricilere projelere katkıda bulunma sürecini açıklayan bölüm.
• Davranış kodu: Davranış kurallarını açıklayan bölüm, bireylerin ve kuruluşların dijital araçla veya topluluklarıyla herhangi bir şekilde etkileşimde bulunurken uymaları gereken sosyal normları, kuralları ve sorumlulukları belirler.
• Rozetler: Aracın durumunu okunabilir ve kısa bir şekilde belirten rozetleri (README.md içine yerleştirilmiş küçük resimler) gösteren bölüm.
• Versiyon: Dijital aracın sürümlerinin ve her sürüme eklenen işlevlerin bir listesini gösteren bölüm.
• Teşekkürler: Projeye bir şekilde katkıda bulunan diğer kişi veya kuruluşlara teşekkürleri içeren bölüm.

Bu bilgiyi genişletmek için İyi uygulamalar konularında belgeleme gelişimi için Ücretsiz yazılımtarafından "Geliştirme Girişimi Kodubaşlıklı bir kılavuz yayınladı del Interamerican Kalkınma Bankası aşağıdaki bağlantıya tıklayabilirsiniz: Belgeler - Dijital araçları yayınlama kılavuzu. Ve diğer yayınlarda atıfta bulunan kısmı inceleyeceğiz. iyi uygulama üzerinde değerlendirme ve lisanslama del Özgür ve Açık Yazılım kendilerini.

Sonuç

Umarız bu "yararlı küçük gönderibaşlıklı bir kılavuz yayınladı hakkında «Buenas prácticas» alanında «documentación» geliştirirken yaratmak «Software libre y abierto», büyük ilgi ve faydalıdır. «Comunidad de Software Libre y Código Abierto» ve harika, devasa ve büyüyen ekosistemin yayılmasına büyük katkı sağlar. «GNU/Linux».

Ve daha fazla bilgi için, herhangi birini ziyaret etmekten her zaman çekinmeyin. Çevrimiçi kitaplık olarak OpenLibra y jedit okumak kitaplar (PDF'ler) bu konu veya diğerleri hakkında bilgi alanları. Şimdilik, bunu beğendiyseniz «publicación», paylaşmayı bırakma başkalarıyla, senin içinde Favori web siteleri, kanallar, gruplar veya topluluklar sosyal ağlar, tercihen ücretsiz ve açık Mastodonveya güvenli ve özel Telegram.

Veya adresindeki ana sayfamızı ziyaret edin DesdeLinux veya resmi Kanala katılın Telgrafı DesdeLinux bu veya diğer ilginç yayınları okumak ve oylamak için «Software Libre», «Código Abierto», «GNU/Linux» ve ilgili diğer konular «Informática y la Computación»Ve «Actualidad tecnológica».