Prinsip Dasar Menulis Dokumentasi yang Baik

Posting ini disumbangkan oleh penulis tamu Jeff Matson. Jeff adalah kepala dokumentasi untuk GravityForms. Dia adalah pencipta plugin WordPress Heartbeat Control dan merupakan penggemar tahun 90-an.

Seringkali, dokumentasi adalah bagian yang paling diremehkan dari proses pengembangan. Ketika kami melihat bintang rock di komunitas WordPress, kami biasanya melihat pengembang, desainer, dan pemasar. Sedikit yang diketahui tentang para penulis dokumentasi di luar sana yang mencurahkan darah, keringat, dan air mata mereka untuk memastikan semuanya berjalan lancar.

Posting ini adalah tentang mereka yang hari demi hari menatap baris kode yang tak ada habisnya untuk menguraikan apa yang dipikirkan pengembang, dan makna sebenarnya di balik kode yang ada.

Dokumentasi yang Baik Lebih dari Kata-kata

Penulis dokumentasi yang baik memberikan lebih dari sekadar instruksi manual, mereka memberikan pengalaman. Saya telah mengenal para dokumenter yang sangat baik, melatih para pemula, dan perbedaan terbesar di antara mereka adalah memahami otak mereka yang membacanya. Layaknya novel, dokumentasi memiliki alur yang membuat pembaca tetap tertarik dan mencerna lebih banyak informasi daripada yang mereka sadari.

Dokumentasi berkualitas menargetkan pengguna yang paling mungkin membacanya. Ini juga memberikan titik referensi bagi mereka yang cenderung tidak membacanya. Misalnya, jika mendokumentasikan hook tertentu, biasanya diasumsikan bahwa pengembang akan membacanya, tetapi bagaimana dengan mereka yang memiliki sedikit pengalaman pengembangan?

Seorang penulis dokumentasi yang baik akan memberikan titik referensi bagi mereka yang membutuhkan lebih banyak dorongan ke arah yang benar, tanpa perlu menghubungi dukungan untuk menjelaskannya bagi mereka.

Dokumentasi Memiliki Dampak Lebih Besar Dari yang Anda Pikirkan

Kebanyakan hanya mengabaikan dokumentasi, mendorongnya ke jurang tak berujung sampai mereka tidak tahan lagi. Saya bersalah atas hal yang sama dalam beberapa kasus. Apa yang tidak disadari oleh orang-orang itu, adalah bahwa setiap saat plugin atau tema mereka tidak didokumentasikan, pengalaman pengguna menderita.

Mari kita lihat tiket dukungan Anda yang paling umum. Jika Anda mendokumentasikan masalah itu dengan lebih baik, apakah tiket itu akan hilang seluruhnya? Mungkin tidak. Apakah Anda akan mendapatkan lebih sedikit tiket mengenai masalah ini serta meningkatkan produktivitas Anda atau agen pendukung Anda? saya jamin. Saya pikir kita semua bisa menggunakan lebih sedikit tiket dukungan.

Seperti yang saya sebutkan sebelumnya, dokumentasi membuat dampak dramatis pada pengalaman pengguna. Jika pengguna dapat menemukan informasi dengan mudah dan efisien, mereka telah menghemat waktu mereka sendiri dan juga waktu Anda. Harapan hidup rata-rata dunia adalah 66,57 tahun dan pengguna Anda lebih suka melakukan sesuatu yang lain dengan hidup mereka daripada mengutak-atik dokumentasi yang ditulis dengan buruk.

Jika pelanggan melihat bahwa Anda telah meluangkan sedikit waktu dan usaha untuk dokumentasi Anda, mereka akan, sadar atau tidak, lebih menghargai Anda. Dokumentasi yang baik menunjukkan bahwa Anda peduli dengan mereka setelah penjualan awal.

Pernahkah Anda dibiarkan tinggi dan kering setelah menghabiskan uang hasil jerih payah dan segera menyesali pembelian itu? Saya pikir kita semua pernah. Dengan dokumentasi yang tepat, Anda dapat menghindari menyampaikan perasaan itu kepada pelanggan Anda.

Bagaimana Anda Dapat Menulis Dokumentasi yang Lebih Baik?

Langkah pertama adalah berhenti menghindarinya. Setelah Anda mahir, menulis dokumentasi lebih merupakan pengalaman yang menyenangkan daripada yang Anda pikirkan. Bahkan, itu akan menjadi sifat kedua. Sama seperti hal lain di dunia, latihan menjadi sempurna.

Salah satu langkah pertama yang ingin Anda ambil ketika memutuskan untuk membawa dokumentasi Anda ke tingkat berikutnya adalah menentukan titik nyeri Anda. Untuk apa Anda dihubungi? Jika Anda mulai menulis secara membabi buta tentang berbagai hal, Anda mungkin menemukan bahwa apa yang Anda tulis tidak memberikan dampak yang Anda inginkan.

Salah satu teknik terbaik yang saya temukan adalah melacak jumlah tiket yang didokumentasikan vs. yang tidak, dan memecah tiket yang tidak masuk kategori. Dengan cara ini, Anda dapat menargetkan titik nyeri dengan lebih baik, dan merevisi bagian-bagian yang mungkin tidak membantu sebagaimana mestinya.

Setelah Anda menentukan dokumentasi apa yang harus Anda tulis, Anda harus menentukan audiens target Anda, dan memecahnya menjadi pengembang, pengguna, dan pengguna yang kuat. Ini membantu Anda melayani audiens tertentu. Kami akan membahas cara menargetkan pengguna tersebut nanti.

Selanjutnya, Anda ingin memecah dokumen. Untuk pengembang, Anda ingin memecahnya menjadi informasi mentah (argumen yang diterima, nilai yang dikembalikan, dll.), contoh spesifik, dan kasus penggunaan. Untuk pengguna, tindakan terbaik adalah panduan. Setiap langkah yang perlu mereka ambil, terlepas dari betapa sepele tampaknya, sangat penting.

Eja itu kepada mereka di setiap langkah. Mendokumentasikan untuk power user sangat mirip dengan skenario pengguna, tetapi lebih terstruktur dan dapat dipindai. Jelaskan, tetapi biarkan mereka melompat dengan mudah ke tempat yang mereka tuju tanpa membaca langkah sebelumnya terlebih dahulu.

Seni Menulis Dokumentasi yang Lebih Baik

Ketika berbicara tentang seni menulis dokumentasi Anda, tulislah dengan cara yang paling menargetkan audiens Anda, tetapi juga gunakan bahasa sederhana yang Anda tahu akan mereka pahami. Salah satu alasan terbaik untuk ini adalah karena terjemahan. Sementara Google translate melakukan pekerjaan yang sangat baik, jauh lebih mudah untuk menerjemahkan kosa kata sederhana dari siswa kelas 5 daripada yang terkandung dalam tesis pasca-sarjana.

Dalam konten Anda, jangan takut untuk menautkan ke konten yang relevan. Ini akan memungkinkan Anda untuk menghindari pengulangan diri Anda melalui banyak dokumen, serta memungkinkan pembaca untuk melacak kembali jika mereka membutuhkan lebih banyak informasi tentang subjek tertentu. Lagi pula, tujuan utama Anda adalah membuat pengguna senang, dan menghemat waktu Anda.

Proses dokumentasi tidak berhenti setelah Anda menekan tombol publish . Kembali dan perbaiki setiap dokumen sesuai kebutuhan. Hampir segera setelah dokumen diterbitkan, kembali dan lihat apakah tiket dukungan yang Anda lacak telah menurun, dan lalu lintas ke artikel tertentu telah meningkat. Biasanya, jika Anda mendapatkan lebih banyak lalu lintas ke sebuah artikel, itu membantu. Jika Anda mendapatkan lebih banyak lalu lintas tetapi jumlah tiket dukungan yang sama, Anda mungkin ingin melihat artikel itu untuk mengetahui alasannya.

Apa yang Kami Pelajari

Pertama, saya berharap setelah sampai sejauh ini, Anda memiliki apresiasi yang lebih baik bagi mereka yang menulis dokumentasi yang kebanyakan dari kita anggap remeh. Ini benar-benar bentuk seni yang banyak dari kita yang menulis dokumentasi untuk mencari nafkah benar-benar menikmati dan menghabiskan banyak waktu.

Saya juga berharap Anda keluar dari artikel ini dengan lebih memikirkan dokumentasi Anda yang ada dan bagaimana hal itu dapat ditingkatkan. Dokumentasi yang tepat bisa sangat bermanfaat dan sekali dalam praktik, sebenarnya bisa sangat menyenangkan untuk ditulis.

Dokumentasikan lebih awal, dokumentasikan sesering mungkin. Produk hebat lebih dari sekadar kode hebat, tetapi juga didokumentasikan dengan indah.