Praktik yang baik untuk mengembangkan Perangkat Lunak bebas dan terbuka: Dokumentasi

La Dokumentasi adalah dan harus menjadi bagian fundamental dari proses dan perencanaan kreatif dari semua aktivitas manusia, dan lebih banyak lagi di bidang teknologi, terutama di bidang Pengembangan perangkat lunak.

El tujuan dari semua dokumentasi itu pasti Dia mengajar pihak ketiga (pengguna, administrator, pengelola, atau pengembang lain), yang biasanya tidak terbiasa dengan file produk (kode, aplikasi atau sistem), bagaimana ini dibuat strukturnya, operasinya dan bahkan jika memungkinkan, alasan pembuatannya serta cara desain dan operasinya.

Selanjutnya, dalam kasus khusus Dokumentasi Perangkat Lunak Gratis sangat penting, karena memungkinkan untuk sepenuhnya menjamin transfer pengetahuan dan pemberdayaan diperlukan untuk pemenuhan yang memuaskan dari 4 kebebasan dipromosikan olehnya, yaitu:

• 0: Kebebasan untuk menjalankan program sesuai keinginan, untuk tujuan apa pun.
• 1: Kebebasan untuk mengakses dan mempelajari program, dan mengubah atau menyesuaikannya untuk keuntungan Anda sendiri.
• 2: Kebebasan untuk membagikan atau mendistribusikan kembali salinan untuk menyebarkan yang sama dan / atau membantu orang lain.
• 3: Kebebasan untuk mendistribusikan salinan dari versi modifikasi Anda kepada pihak ketiga.

Dokumentasi yang baik memungkinkan, oleh karena itu, produk yang dibuat:

• Ini digunakan dengan benar, dan itu lebih mudah diajarkan dan dipelajari.
• Dipahami sepenuhnya oleh mereka yang ingin memodifikasinya untuk meningkatkan atau menyesuaikannya.
• Dibagikan dan diterima dengan lebih percaya diri, di antara semua kenalan potensial dan orang asing.
• Miliki massa yang lebih baik di antara masyarakat.

Praktik yang baik: Dokumentasi

Dasar-dasar

Dalam kasus Pengembangan Perangkat Lunak Gratis dan Sumber Terbuka, umumnya, pengguna utama dokumentasi relatif terhadap desain produk, apakah yang sedang atau akan menjadi, the bertanggung jawab untuk pemeliharaan yang sama. Dan tanpa dokumentasi yang baik atau tidak sama sekali, satu-satunya alternatif yang layak adalah dengan menjelajahinya secara langsung, untuk mencapainya memahami desain dan fungsinya.

Tidak membuat dokumentasi yang baik saat berhubungan mengembangkan Perangkat Lunak Gratis, Sumber Terbuka atau jenis perangkat lunak lainnya, akan dikirim ke penerima yang memungkinkan (pengguna, administrator, pengelola, atau pengembang lain) untuk menemukan jalan melalui hutan tanpa peta atau kompas.

Buat dokumentasi yang bagus untuk masing-masing Perangkat Lunak Gratis, Sumber Terbuka itu juga bermanfaat, karena mendokumentasikan memiliki biayaInvestasi, jika dilakukan dengan benar, sangat berharga. Karena, dunia Perangkat lunak penuh dengan cerita tentang kode warisan program, aplikasi atau sistem lama atau terkini, yang hanya sedikit orang yang berani menyentuh, karena hampir tidak ada yang mengerti. Pemrogram fokus pada pembuatan kode dan tidak mendokumentasikannya dengan benar dan lengkap. Dan ini harus diperbaiki.

Praktik yang baik tentang dokumentasi dalam file teks README

Dalam kasus Perangkat Lunak Gratis dan Sumber Terbuka, dokumentasi sering kali dibatasi pada file teks, jika dibuat oleh individu atau kelompok kecil pemrogram atau komunitas. Tapi, hingga membuat dokumentasi sederhana menggunakan simple file teks README.md (atau .txt) Anda dapat memiliki praktik terbaik atau baik, tip atau panduan pembuatan yang berguna untuk memberikan kepada pihak ketiga informasi paling lengkap dan mendetail yang diperlukan tentang pembuatan.

Untuk artikel kami, kami telah mengambil Praktik yang baik disusun dan diungkapkan oleh "Kode untuk Inisiatif Pembangunan" itu Bank Pembangunan Interamerican, yang secara ringkas memberi tahu kita bahwa dokumentasi yang baik berdasarkan a file teks README.md (atau .txt) Itu harus disusun sebagai berikut:

Struktur file README yang direkomendasikan

• Deskripsi dan konteks: Bagian di mana fungsionalitas harus dijelaskan, konteks di mana ia dikembangkan dan masalah pengembangan yang dipecahkannya.
• Panduan Pengguna: Bagian di mana instruksi kepada pengguna akhir tentang cara mulai menggunakan alat digital harus disebutkan.
• Petunjuk pemasangan: Bagian di mana petunjuk instalasi untuk menggunakan kembali dan mengkonfigurasi alat digital harus disebutkan. Bagian ini ditujukan untuk pengembang.
• penulis Bagian di mana kredit harus diberikan kepada kolaborator alat.
• Lisensi untuk kode alat: Bagian di mana izin yang diberikan kepada pihak ketiga untuk menggunakan kembali alat digital harus ditentukan.
• Lisensi untuk dokumentasi alat: Bagian di mana jenis lisensi yang terdapat dalam dokumentasi yang dibuat harus disebutkan.

Dalam hal ini praktik yang baik, mereka juga merekomendasikan untuk menambahkan Dokumentasi file README agar lebih lengkap, berikut bagiannya:

• Bagaimana cara berkontribusi: Bagian yang menjelaskan kepada pengembang baru proses untuk berkontribusi pada proyek.
• Kode etik: Bagian yang menjelaskan kode etik menetapkan norma, aturan, dan tanggung jawab sosial yang harus diikuti oleh individu dan organisasi ketika berinteraksi dengan alat digital atau komunitasnya.
• Lencana: Bagian yang menampilkan lencana (gambar kecil yang disematkan di README.md) yang menentukan status alat dengan cara yang dapat dibaca dan ringkas.
• Versi: kapan: Bagian yang menunjukkan daftar versi alat digital dan fungsionalitas yang ditambahkan ke setiap versi.
• Ucapan Terima Kasih: Bagian yang berisi ucapan terima kasih kepada orang atau organisasi lain yang telah berkontribusi dalam beberapa cara untuk proyek.

Untuk memperluas informasi ini, di Praktik yang baik dalam hal dokumentasi untuk pengembangan perangkat lunak bebas, oleh "Kode untuk Inisiatif Pembangunan" itu Bank Pembangunan Interamerican Anda dapat mengklik tautan berikut: Dokumentasi - Panduan untuk menerbitkan alat digital. Dan dalam publikasi lain kita akan membahas bagian yang dimaksud praktik yang baik pada evaluasi dan perizinan itu Perangkat Lunak Bebas dan Terbuka diri.

Kesimpulan

Kami berharap itu ini "posting kecil yang bermanfaat" tentang «Buenas prácticas» dalam bidang «documentación» untuk membuat saat berkembang «Software libre y abierto», sangat menarik dan berguna, untuk keseluruhan «Comunidad de Software Libre y Código Abierto» dan memberikan kontribusi besar bagi penyebaran ekosistem aplikasi yang indah, raksasa, dan berkembang dari dan untuk «GNU/Linux».

Dan untuk informasi lebih lanjut, jangan sungkan untuk mengunjungi Perpustakaan online sebagai BukaLibra y jedi untuk membaca buku (PDF) tentang topik ini atau lainnya bidang pengetahuan. Untuk saat ini, jika Anda menyukai ini «publicación», jangan berhenti membagikannya dengan orang lain, di Situs web, saluran, grup, atau komunitas favorit jaringan sosial, lebih disukai yang gratis dan terbuka sebagai Mastodon, atau sejenisnya yang aman dan pribadi Telegram.

Atau cukup kunjungi beranda kami di DesdeLinux atau bergabung dengan Channel resmi Telegram dari DesdeLinux untuk membaca dan memilih publikasi ini atau publikasi menarik lainnya di «Software Libre», «Código Abierto», «GNU/Linux» dan topik lain yang terkait dengan «Informática y la Computación», Dan «Actualidad tecnológica».