Dokumentasi teknikal bukanlah tugasan sampingan yang anda selesaikan selepas kod berjaya dikompil. Ia berada di tengah-tengah setiap projek perisian, menentukan sama ada pembangun baharu boleh membaiki pepijat pada hari pertama mereka atau sama ada pengguna meninggalkan produk anda selepas lima minit berasa keliru. Dokumentasi yang baik membantu pengguna menyelesaikan tugasan sebenar. Ia membantu penyelenggara masa hadapan memahami mengapa sesuatu modul wujud dan cara mengubahnya tanpa merosakkan segalanya. Namun, terlalu banyak pasukan menganggap dokumentasi sebagai perkara sampingan, README yang dibuat secara tergesa-gesa, atau halaman wiki yang dibiarkan usang. Menulis dokumentasi yang benar-benar berguna adalah kemahiran yang boleh anda tingkatkan secara sengaja.
Kenali Pembaca Anda Sebelum Menulis
Sebelum anda menaip satu tajuk pun, tentukan siapa yang membaca. Seorang pentadbir pangkalan data yang mencari tetapan kolam sambungan (connection pool settings) tidak mempunyai persamaan dengan pembangun front-end yang mencari props komponen React. Pengguna akhir memerlukan langkah bernombor dan tangkapan skrin, bukan rajah seni bina. Mereka ingin tahu cara mengeksport PDF, bukan bagaimana saluran paip rendering (rendering pipeline) berfungsi. Pembangun yang menyepadukan perpustakaan (library) anda memerlukan tandatangan fungsi yang tepat, kod ralat, dan petikan kod (snippets) yang boleh disalin dan ditampal. Pentadbir sistem memerlukan prasyarat pemasangan, pemboleh ubah persekitaran (environment variables), dan aliran penyelesaian masalah yang bermula dengan mod kegagalan yang paling biasa.
Jika anda cuba melayani ketiga-tiga kumpulan tersebut dengan satu blok teks yang panjang, semua orang akan rugi. Cipta laluan berasingan. Malah satu halaman pun boleh dibahagikan dengan kemas menggunakan tajuk yang jelas seperti "Untuk pengendali" dan "Untuk pembangun klien." Matlamatnya adalah untuk menghapuskan kekeliruan mental seperti bertanya, "Adakah perenggan ini untuk saya?"
Kurangkan Gangguan
Kejelasan lebih penting daripada kepintaran. Gunakan ayat yang pendek. Gunakan ayat aktif. "Initialize the database" adalah lebih jelas daripada "The database should be initialized by the user." Apabila anda perlu menggunakan istilah teknikal seperti "idempotency" atau "serialization," definisikan ia secara dalam talian atau pautkan ke glosari. Jangan andaikan pembaca mempunyai pengetahuan sedia ada.
Satu ujian praktikal: cuba baca perenggan anda dengan kuat. Jika anda kehabisan nafas, ayat itu terlalu panjang. Satu lagi ujian: gantikan kata kerja yang berbunga-bunga dengan kata kerja yang mudah. Jika frasa seperti "utilize the API" boleh menjadi "use the API" tanpa hilang maksudnya, lakukan perubahan tersebut. Bahasa yang mudah bukan bermaksud bahasa yang merendah-rendahkan tahap pemikiran. Ia bermaksud bahasa yang tepat tanpa hiasan korporat yang tidak perlu.
Struktur yang Benar-benar Membantu
Manual yang tidak teratur membazirkan lebih banyak masa berbanding tiada manual langsung. Anggap dokumentasi anda sebagai sebuah corong. Di bahagian atas, letakkan ringkasan ringkas yang menjelaskan apa yang dilakukan oleh projek tersebut dan siapa yang perlu mengambil tahu. Ikuti dengan arahan pemasangan yang tidak mengandaikan apa-apa tentang tetapan tempatan pembaca. Kemudian, tambah tutorial yang membimbing melalui senario lengkap dan realistik dari mula hingga tamat. Rujukan API menyusul selepas itu. Ini haruslah menyeluruh tetapi mudah diimbas, dikumpulkan mengikut sumber atau fungsi dan bukannya disusun mengikut urutan abjad. Akhir sekali, letakkan panduan penyelesaian masalah yang menangani simptom tertentu. Seorang pengguna yang menerima "Connection refused" memerlukan jawapan yang berbeza daripada pengguna yang melihat "Permission denied." Kumpulkan ralat mengikut mesej atau konteks, bukan mengikut kategori abstrak.
Senarai dan blok kod memecahkan teks yang padat dan membolehkan pembaca mengimbas arahan tepat yang mereka perlukan. Senarai bulet yang diletakkan dengan betul boleh mengubah perenggan yang mengelirukan kepada urutan tindakan.
Tunjukkan, Jangan Sekadar Beritahu
Penjelasan abstrak mengecewakan pengguna. Jika anda menerangkan cara mengkonfigurasi alat, tunjukkan kandungan fail yang tepat. Sediakan petikan kod untuk pemasangan, untuk inisialisasi, dan untuk konfigurasi biasa. Tunjukkan contoh input dan output yang dijangkakan secara bersebelahan. Jika API anda mengembalikan JSON, tunjukkan JSON tersebut. Jika alat CLI menghasilkan output berbentuk jadual, tunjukkan jadual itu. Jangan sesekali menganggap bahawa penerangan tentang aliran kerja adalah setara dengan demonstrasi.
Yang paling penting, uji setiap contoh dalam persekitar