Good morning, coders and developer wherever you are, how are you today?
Mungkin lebih tepatnya tulisan saya kali ini bagi anda pecinta git :D khusus nya bagi dokumenter yang sering berkutat dengan markdown readme, apa itu? Menurut wikipedia Sebuah readme file berisi informasi tentang file lain dalam direktori atau arsip dan sangat umum didistribusikan dengan perangkat lunak komputer. Hal ini dibutuhkan oleh seseorang terkait informasi pada source yang telah anda distribusikan, sedangkan untuk komponen readme sendiri kurang lebih terdiri dari beberapa komponen berikut :

- instruksi konfigurasi
- petunjuk instalasi
- instruksi pengoperasian
- manifest berkas
- hak cipta dan perizinan informasi
- Informasi kontak untuk distributor atau programmer
- bug yang ditemukan
- penyelesaian masalah
- credit dan acknowledgment
- changelog

README yang baik adalah singkat dan to the points dan terkait kriteria nya beberapa ulasan di beberapa forum readme yang baik itu yang memperhatikan beberapa hal berikut :

• Nama proyek dan semua sub-modul dan perpustakaan (kadang-kadang mereka diberi nama yang berbeda dan sangat membingungkan bagi pengguna baru).
• Deskripsi dari semua proyek, dan semua sub-modul dan perpustakaan.
• Kode line dimana ini berisi scripting tentang bagaimana source anda digunakan (patut diperhatikan pada source libraray)
• Hak cipta dan perizinan (biasanya  "Read LISENSI")
• Instruksi untuk mengambil dokumentasi
• Petunjuk untuk menginstal, mengkonfigurasi, dan menjalankan program
• Instruksi untuk mengambil kode terbaru dan petunjuk rinci untuk development (atau gambaran singkat, biasanya ada pada "INSTALL")
• Daftar penulis atau "Authors"
• Instruksi untuk melaporkan bug, permintaan fitur, mengirimkan patch, bergabung dengan milis, dapatkan notif, atau bergabung dengan pengguna atau developer.
• Info lain kontak (alamat email, website, nama perusahaan, alamat, dll)
• Sejarah singkat jika penggantian atau fork dari sesuatu yang lain
• Pemberitahuan hukum (kripto)

Beberapa contoh readme yang baik adalah salah satunya milik gnu dan bisa anda pelajari juga dengan mengamati penulisan dokumentasi dari project besar lainnya terkait apache, opensources based, dsb bisa di jadikan acuan yang baik untuk menulis dokumentasi yang baik.

Beberapa tradisi Unix juga akan di paparkan dibawah dan secara global biasanya markdown README nya berbentuk html dengan format sebagai berikut :

• Karakter ASCII, jika README yang ditulis dalam bahasa Inggris
• Menulis dalam bahasa Inggris jika mungkin, dan untuk versi terjemahan dengan dua huruf kode bahasa ekstensi seperti README.id
• Kurang lebih 80 karakter per baris
• Baris kosong antara paragraf
• Strip di bawah header
• Indent menggunakan spasi (0x20) bukan tab

Mungkin secara garis besar telah termuat dalam rangkuman diatas, namun terkadang sebagian besar README masih terlalu verbose. Sebuah README adalah file pertama seseorang harus membaca ketika menghadapi source code sumber, dan harus ditulis sebagai sangat singkat, penjelasan awal untuk perangkat lunak. Ini harus berisi nama kode, versi, mungkin tanggal terakhir diperbarui, dan sangat singkat, tingkat tinggi ikhtisar perangkat lunak, selain kemungkinan referensi ke file mana yang berisi informasi lain bahwa seseorang mungkin akan tertarik seperti petunjuk instalasi (di INSTALL), penulis (dalam AUTHORS), atau sejarah (di ChangeLog atau ReleaseNotes). README merupakan pengantar. Ini harus mengasumsikan pembaca tahu apa-apa tentang perangkat lunak dan harus memberikan pengantar singkat. Jika perangkat lunak yang skenario, README akan menjadi tagline 10 detik digunakan untuk pitch script untuk produser. Jika seseorang selesai membaca pertama 10 baris NamaSource / README dan tidak tahu apakah itu adalah library widget, software akuntansi, atau video game, maka penulis README telah gagal.

Sekian dari saya, semoga bisa bermanfaat dan menjadikan diri kita lebih baik dan terbuka wawasan yang lebih, terimakasih.

./ creatorb (creatorb.github.io)