Amalan baik untuk membangunkan Perisian bebas dan terbuka: Dokumentasi

La dokumentasi adalah dan harus menjadi bahagian asas dari proses dan perancangan kreatif semua aktiviti manusia, dan lebih banyak lagi dalam bidang teknologi, terutama di kawasan Pembangunan perisian.

El tujuan semua dokumentasi mesti Dia mengajar pihak ketiga (pengguna, pentadbir, penyelenggara, atau pembangun lain), yang biasanya tidak biasa dengan produk (kod, aplikasi atau sistem), bagaimana ia dicipta strukturnya, operasinya dan walaupun mungkin, alasan untuk membuat dan cara reka bentuk dan pengoperasiannya.

Selanjutnya, dalam kes khusus Dokumentasi Perisian Percuma sangat penting, kerana memungkinkan untuk menjamin sepenuhnya pemindahan pengetahuan dan pemerkasaan perlu untuk pemenuhan yang memuaskan 4 kebebasan dipromosikan olehnya, iaitu:

• 0: Kebebasan untuk menjalankan program seperti yang dikehendaki, untuk tujuan apa pun.
• 1: Kebebasan untuk mengakses dan mempelajari program, dan mengubah atau menyesuaikannya untuk kepentingan anda sendiri.
• 2: Kebebasan untuk berkongsi atau mengedarkan semula salinan untuk menyebarkan yang sama dan / atau menolong orang lain.
• 3: Kebebasan untuk mengedarkan salinan versi yang anda ubah suai kepada pihak ketiga.

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

• Ia digunakan dengan betul, dan lebih mudah diajar dan dipelajari.
• Fahami sepenuhnya oleh mereka yang ingin mengubahnya untuk memperbaikinya atau menyesuaikannya.
• Dikongsi dan diterima dengan lebih yakin, di antara semua kenalan dan orang asing yang berpotensi.
• Mempunyai jisim yang lebih baik di kalangan orang ramai.

Amalan baik: Dokumentasi

Asas

Dalam kes Pembangunan Perisian Percuma dan Sumber Terbuka, secara amnya, pengguna utama dokumentasi berkaitan dengan reka bentuk produk, adakah itu yang atau akan menjadi, bertanggungjawab untuk penyelenggaraan yang sama. Dan tanpa dokumentasi yang baik atau tidak, satu-satunya alternatif yang dapat dilaksanakan adalah dengan meneroka secara langsung, untuk dicapai memahami reka bentuk dan fungsinya.

Tidak membuat dokumentasi yang baik ketika datang membangunkan Perisian Percuma, Sumber Terbuka atau jenis perisian lain, adalah untuk dihantar kepada penerima yang mungkin (pengguna, pentadbir, penyelenggara, atau pembangun lain) untuk mencari jalan melalui hutan tanpa peta atau kompas.

Buat dokumentasi yang baik untuk masing-masing Perisian Percuma, Sumber Terbuka ia juga bermanfaat, kerana, walaupun mendokumentasikan mempunyai kosPelaburan, jika dilakukan dengan betul, sangat berbaloi. Kerana, dunia perisian penuh dengan cerita mengenai kod warisan program, aplikasi atau sistem lama atau semasa, yang hanya sedikit orang yang berani menyentuh, kerana hampir tidak ada yang memahami. Pengaturcara memberi tumpuan untuk membuat kod dan tidak mendokumentasikannya dengan betul dan lengkap. Dan ini mesti diatasi.

Amalan baik mengenai dokumentasi dalam fail teks README

Dalam kes Perisian Percuma dan Sumber Terbuka, dokumentasi sering dibatasi pada fail teks, apabila dibuat oleh individu atau kumpulan kecil pengaturcara atau komuniti. Tetapi, sehingga membuat dokumentasi ringkas menggunakan yang sederhana fail teks README.md (atau .txt) anda boleh memiliki amalan terbaik atau baik, petua atau panduan penciptaan yang berguna untuk membawa kepada pihak ketiga maklumat yang paling lengkap dan terperinci yang diperlukan mengenai penciptaan itu.

Untuk artikel kami, kami telah mengambil Amalan baik dikandung dan didedahkan oleh "Kod untuk Inisiatif Pembangunan" yang Bank Pembangunan Interamerican, yang secara ringkas memberitahu kita bahawa dokumentasi yang baik berdasarkan a fail teks README.md (atau .txt) Ia mesti disusun seperti berikut:

Struktur fail README yang disyorkan

• Penerangan dan konteks: Bahagian di mana fungsi mesti dijelaskan, konteks di mana ia dikembangkan dan masalah pembangunan yang dapat diselesaikannya.
• Panduan pengguna: Bahagian di mana arahan kepada pengguna akhir mengenai cara mula menggunakan alat digital harus disebutkan.
• Panduan pemasangan: Bahagian di mana arahan pemasangan untuk menggunakan semula dan mengkonfigurasi alat digital harus disebutkan. Bahagian ini bertujuan untuk pembangun.
• penulis Bahagian di mana kredit mesti diberikan kepada kolaborator alat tersebut.
• Lesen untuk kod alat: Bahagian di mana kebenaran yang diberikan kepada pihak ketiga untuk menggunakan semula alat digital mesti ditentukan.
• Lesen untuk dokumentasi alat: Bahagian di mana jenis lesen yang terdapat dalam dokumentasi yang dibuat mesti disebutkan.

Dalam ini amalan yang baik, mereka juga mengesyorkan menambah ke Dokumentasi fail README untuk menjadikannya lebih lengkap, bahagian berikut:

• Cara menyumbang: Bahagian yang menerangkan kepada pemaju baru proses untuk menyumbang kepada projek.
• Tatakelakuan: Bahagian yang menerangkan kod tingkah laku menetapkan norma, peraturan dan tanggungjawab sosial yang mesti dipatuhi oleh individu dan organisasi ketika berinteraksi dengan alat digital atau komuniti mereka.
• Lencana: Bahagian yang menunjukkan lencana (gambar kecil tertanam di README.md) yang menentukan keadaan alat ini dengan mudah dibaca dan ringkas.
• Versi: Bahagian yang menunjukkan senarai versi alat digital dan fungsi yang ditambahkan ke setiap versi.
• Ucapan terima kasih: Bahagian yang mengandungi ucapan terima kasih kepada orang lain atau organisasi yang telah memberikan sumbangan dalam projek ini.

Untuk mengembangkan maklumat ini, di Amalan baik dalam perkara dokumentasi untuk pembangunan Perisian Percuma, oleh "Kod untuk Inisiatif Pembangunan" yang Bank Pembangunan Interamerican anda boleh mengklik pada pautan berikut: Dokumentasi - Panduan untuk menerbitkan alat digital. Dan dalam penerbitan lain, kita akan meneroka bahagian yang dimaksudkan amalan yang baik mengenai penilaian dan pelesenan yang Perisian Percuma dan Terbuka diri mereka.

Kesimpulan

Kami berharap bahawa ini "jawatan kecil yang berguna" kira-kira «Buenas prácticas» dalam bidang «documentación» untuk mencipta semasa membangun «Software libre y abierto», menjadi perhatian dan kepentingan yang besar, untuk keseluruhannya «Comunidad de Software Libre y Código Abierto» dan memberikan sumbangan besar kepada penyebaran ekosistem aplikasi dan untuk ekosistem yang hebat, besar dan berkembang «GNU/Linux».

Dan untuk maklumat lebih lanjut, jangan ragu untuk mengunjungi mana-mana Perpustakaan dalam talian sebagai OpenLibra y jedit untuk membaca buku (PDF) mengenai topik ini atau lain-lain bidang pengetahuan. Buat masa ini, jika anda menyukai ini «publicación», jangan berhenti berkongsi dengan orang lain, di anda Laman web, saluran, kumpulan, atau komuniti kegemaran rangkaian sosial, lebih baik percuma dan terbuka sebagai Mastodon, atau selamat dan peribadi seperti Telegram.

Atau hanya lawati halaman utama kami di DesdeLinux atau menyertai Saluran rasmi Telegram daripada DesdeLinux untuk membaca dan memilih ini atau penerbitan menarik lain di «Software Libre», «Código Abierto», «GNU/Linux» dan topik lain yang berkaitan dengan «Informática y la Computación», dan «Actualidad tecnológica».