Pengembang Mengapa Anda Seharusnya Tidak Melewatkan Dokumentasi

Dalam ranah pengembangan aplikasi seluler, aplikasi web, aplikasi desktop, atau pustaka JavaScript, dokumentasi memainkan peran penting yang dapat menentukan keberhasilan pengembangan perangkat lunak. Tetapi jika Anda pernah melakukan dokumentasi, Anda akan setuju dengan saya bahwa itu adalah hal yang paling tidak favorit untuk dilakukan oleh pengembang.

Tidak seperti menulis kode (yang harus dilakukan oleh pengembang), dokumentasi (yang tidak kami miliki) harus dan harus mudah dicerna oleh semua orang. Secara teknis, kita harus menerjemahkan bahasa mesin (kode) ke dalam bahasa yang dapat dimengerti oleh manusia, yang lebih sulit daripada kedengarannya.

Meskipun itu bisa menjadi beban nyata, menulis dokumentasi itu penting dan akan memberikan keuntungan bagi pengguna Anda, kolega Anda, dan terutama Anda sendiri.

Dokumentasi yang Baik Membantu Pengguna

Dokumentasi membantu pembaca memahami cara kerja kode, jelas. Tetapi banyak pengembang membuat kesalahan dengan mengasumsikan bahwa pengguna perangkat lunak akan mahir. Oleh karena itu, dokumentasi mungkin merupakan materi yang tipis, melewatkan banyak hal penting yang seharusnya ada sejak awal. Jika Anda mahir dalam bahasa tersebut, Anda bisa mencari tahu sendiri atas inisiatif Anda; jika tidak, maka Anda tersesat.

Dokumentasi yang ditujukan untuk pengguna biasanya terdiri dari penggunaan praktis atau “bagaimana caranya”. Aturan praktis ketika membuat dokumentasi untuk pengguna umum adalah itu itu harus jelas. Menggunakan kata-kata ramah-manusia lebih disukai daripada istilah teknis atau jargon. Contoh penggunaan nyata juga akan sangat dihargai.

Desain tata letak yang baik juga akan sangat membantu pengguna memindai setiap bagian dokumentasi tanpa ketegangan mata. Beberapa contoh yang bagus (alias favorit saya) adalah dokumentasi untuk Bootstrap dan WordPress ' “Langkah Pertama Dengan WordPress”.

Ini Membantu Pengembang Lain Juga

Setiap pengembang akan memiliki gaya pengkodean sendiri. Tetapi, ketika harus bekerja dalam sebuah tim, kita sering harus berbagi kode dengan rekan tim yang lain. Jadi itu penting untuk memiliki konsensus tentang standar untuk menjaga semua orang di halaman yang sama. Dokumentasi yang ditulis dengan benar akan menjadi referensi yang dibutuhkan tim

Tetapi tidak seperti dokumentasi pengguna akhir, dokumentasi ini biasanya menjelaskan prosedur teknis seperti konvensi penamaan kode, menunjukkan bagaimana halaman tertentu harus dibangun, dan bagaimana API bekerja bersama dengan contoh kode. Seringkali kita juga harus menulis dokumentasi sesuai dengan kode (dikenal sebagai komentar) untuk menjelaskan apa yang dilakukan kode.

Selain itu, dalam kasus di mana Anda miliki anggota baru bergabung tim Anda nanti, dokumentasi ini bisa menjadi cara yang efektif untuk melatih mereka, jadi Anda tidak perlu memberi mereka run-time 1-on-1 pada kode.

Anehnya Itu Juga Membantu Para Coder

Yang lucu tentang pengkodean adalah terkadang bahkan pengembang sendiri tidak memahami kode yang telah mereka tulis. Ini khususnya benar dalam kasus-kasus di mana kode tidak tersentuh selama berbulan-bulan atau bahkan bertahun-tahun.

Kebutuhan yang mendadak untuk meninjau kembali kode-kode itu karena satu dan lain alasan akan membuat orang bertanya-tanya apa yang terjadi dalam pikiran mereka ketika mereka menulis kode-kode ini. Jangan kaget: Saya pernah berada dalam situasi ini sebelumnya. Ini adalah tepat ketika saya berharap Saya telah mendokumentasikan kode saya dengan benar.

Dengan mendokumentasikan kode Anda, Anda akan dapat mencapai bagian bawah kode Anda dengan cepat dan tanpa frustrasi, menghemat banyak waktu Anda yang dapat dihabiskan untuk mendapatkan perubahan di.

Apa yang Membuat Dokumentasi yang Baik?

Ada beberapa faktor yang membangun dokumentasi yang bagus.

1. Jangan Menganggap

Jangan berasumsi bahwa pengguna Anda tahu apa kamu tahu juga apa mereka ingin tahu. Itu selalu lebih baik mulai dari awal terlepas dari tingkat kemahiran pengguna.

Jika Anda membuat plugin jQuery, misalnya, Anda dapat mengambil inspirasi dari dokumentasi SlickJS. Ini menunjukkan bagaimana menyusun HTML, tempat meletakkan CSS dan JavaScript, bagaimana menginisialisasi plugin jQuery pada level paling dasar, dan bahkan menunjukkan markup akhir yang lengkap setelah menambahkan semua hal ini, yang merupakan sesuatu yang jelas.

Intinya adalah dokumentasi ditulis dengan proses pemikiran pengguna, bukan pengembang. Mendekati dokumentasi Anda sendiri dengan cara ini akan memberi Anda perspektif yang lebih baik dalam mengatur karya Anda sendiri.

2. Ikuti Standar

Dalam menambahkan dokumentasi yang sejalan dengan kode, gunakan standar yang diharapkan dari bahasa tersebut. Itu selalu merupakan ide yang baik untuk menggambarkan setiap fungsi, variabel, serta nilai yang dikembalikan oleh fungsi. Berikut adalah contoh dokumentasi inline yang bagus untuk PHP.

 / ** * Menambahkan kelas khusus ke array kelas tubuh. * * @param array $ classes Kelas untuk elemen tubuh. * @return array * / function body_classes ($ class) // Menambahkan kelas grup-blog ke blog dengan lebih dari 1 penulis yang diterbitkan. if (is_multi_author ()) $ classes [] = 'grup-blog';  mengembalikan $ kelas;  add_filter ('body_class', 'body_classes'); 

Berikut ini adalah beberapa referensi untuk memformat dokumentasi sebaris dengan praktik terbaik di PHP, JavaScript, dan CSS:

• PHP: Standar Dokumentasi PHP untuk WordPress
• JavaScript: GunakanJSDoc
• CSS: CSSDoc

Jika Anda menggunakan SublimeText, saya sarankan untuk menginstal DocBlockr yang secara cerdik akan mengisi kode Anda dengan dokumentasi sebaris.

3. Elemen grafis

Gunakan elemen grafis, mereka berbicara lebih baik daripada teks. Media ini sangat berguna, terutama jika Anda membangun perangkat lunak dengan antarmuka grafis. Anda dapat menambahkan elemen pengarah seperti panah, lingkaran, atau apa pun yang dapat membantu pengguna untuk mengetahui ke mana harus pergi untuk menyelesaikan langkah-langkah tersebut, tanpa menebak-nebak.

Berikut ini adalah contoh dari aplikasi Menara tempat Anda dapat mengambil inspirasi. Mereka secara efisien menjelaskan bagaimana cara kerja kontrol versi dengan cara yang menyenangkan yang membuatnya lebih dimengerti daripada menggunakan baris perintah teks biasa.

4. Sectioning

Anda dapat mempertimbangkan untuk membungkus beberapa hal dalam dokumentasi di dalam daftar dan tabel berpoin karena ini membuat konten yang lebih lama lebih mudah untuk dipindai dan dibaca pengguna..

Tambahkan daftar isi dan pisahkan dokumentasi dalam bagian-bagian yang mudah dicerna, namun tetap pertahankan setiap bagian dengan yang berikutnya. Jaga agar tetap pendek dan mudah. Di bawah ini adalah contoh dokumentasi yang tertata rapi di Facebook. Daftar isi membawa kita ke tempat yang ingin kita lompat dalam satu klik.

5. Revisi dan Perbarui

Terakhir, tinjau dokumentasi untuk kesalahan dan revisi bila perlu atau dan setiap kali ada perubahan signifikan pada produk, perangkat lunak, atau perpustakaan. Dokumentasi Anda tidak akan berguna bagi siapa pun jika tidak diperbarui secara teratur bersama produk Anda.