Empat jenis dokumentasi didistribusikan di sepanjang dua sumbu: teori-praktik dan kerja-latihan.
Dua posting sensasional keluar baru-baru ini:
Dan banyak yang bertanya, "Seseorang tolong ajari saya cara menulis dokumentasi yang baik."
Saya tidak mengklaim sebagai ahli, tetapi saya pikir saya ahli dalam hal itu.
Saya sudah cukup minum kopi dan saya akan mencoba menjelaskan apa yang saya tahu.
TL; DR: menulis dokumentasi untuk memecahkan masalah tertentu untuk sekelompok orang tertentu, bukan hanya untuk memiliki dokumentasi.
Tulis dengan baik
Pertama, Anda harus pandai menulis. Penulis Drunken Revelations dengan jelas menyangkal klaim ini, tetapi untuk sebagian besar mungkin tidak berhasil. Anda harus dapat mengambil topik dan menemukan poin utama, menunjukkan detail kunci. Rincian ini perlu diurutkan dengan benar dan kemudian diterjemahkan ke dalam kalimat yang jelas.
Tulisan yang bagus bukan hanya tentang dokumentasi, tentu saja. Anda dapat menguji kemampuan Anda di bidang ini dengan jenis tulisan apa pun. Bisakah Anda menulis bagaimana menemukan sesuatu di rumah Anda? Bisakah Anda menulis pidato singkat? Jika Anda perlu bekerja di bidang ini, saya sarankan Anda berlatih menulis sesuatu selain dokumentasi. Menulis posting blog, menulis cerita pendek, menulis surat kepada teman, apa pun. Jika Anda tidak membaca buku secara teratur, mulailah sekarang. Otak Anda perlu dilatih pada banyak teks yang ditulis dengan baik sebelum Anda dapat membedakan mana yang berhasil dan mana yang tidak dalam kasus khusus Anda. Kembangkan keterampilan mengedit yang sangat berbeda dengan keterampilan menulis (menulis menjadi lebih mudah,jika Anda memercayai keterampilan mengedit Anda - Anda tidak akan terlalu memfilter diri sendiri).
Saran yang paling berguna untuk menulis dokumentasi adalah menulis dengan gaya percakapan. Jauh lebih mudah untuk memahami informasi dari teks informal.
Jenis dokumentasi
Oke, sekarang kembali ke dokumentasi.
Ada berbagai jenis dokumentasi, dan orang-orang membuat tali dari diri mereka sendiri, mencoba mendapatkan satu jenis dokumentasi untuk melakukan pekerjaan yang lain. Peregangan berjalan di sepanjang dua sumbu:
- Informasi untuk pelatihan VS informasi untuk bekerja.
- Langkah-langkah praktis VS informasi teoritis.
(Ini bukan pikiran saya, saya melihatnya di https://documentation.divio.com/ )
Informasi pelatihan yang berisi langkah-langkah praktis disebut tutorial. Jika tidak mengandung langkah-langkah praktis, ini adalah penjelasannya. Kedua hal ini cenderung lebih cocok untuk pemula, jadi mereka harus fokus menjelaskan konsep dan istilah (dan informasi latar belakang). Dalam hal penjelasan, sangat membantu untuk memiliki ringkasan singkat di bagian atas.
Aman untuk berasumsi bahwa, berkat informasi tentang kapan Anda bekerja, seseorang sudah memiliki gambaran umum tentang apa yang sedang terjadi.
Informasi teoretis yang digunakan dalam karya disebut referensi. Ini termasuk dokumentasi untuk setiap metode. Dokumentasi bantuan adalah tempat yang sama sekali tidak berguna untuk menyelenggarakan tutorial.
Jika ini bukan teori, maka panduan ini. Panduan ini pada dasarnya mirip dengan tutorial, dengan dua perbedaan penting: ini mengasumsikan beberapa keakraban dengan topik dan tujuannya adalah untuk menyelesaikan tugas tertentu, bukan untuk mengajar. Daftar periksa adalah panduan cepat, tetapi tetap dapat membantu jika sangat mudah untuk melupakan langkah penting. Gunakan panduan ketika ada langkah yang perlu Anda ulangi. Mereka sangat berharga ketika orang yang melakukan langkah-langkah tidak tahu bagaimana menyelesaikan tugas (baik seseorang di tim lain, atau Anda dalam setahun).
Pilih jenis dokumentasi untuk ditulis berdasarkan kebutuhan pembaca Anda. Mungkin kode Anda sebenarnya cukup mendokumentasikan diri sendiri, dan membaca tanda tangan metode benar-benar memberi tahu Anda apa yang dilakukan metode tersebut. Luar biasa. Ini untuk dokumentasi referensi. Sekarang tulis tiga jenis lainnya.
Jika yang Anda miliki hanyalah dokumentasi referensi, informasi tersebut akan menjadi kumpulan fakta acak yang tidak berguna bagi pembaca yang tidak terbiasa dengan dasar-dasarnya. Dokumentasi bantuan seperti memiliki deskripsi rinci tentang persimpangan ketika pembaca baru mencari peta jalan raya.
Saya pikir sebenarnya ada jenis dokumentasi kelima: remah roti. Ini adalah komentar kecil dalam kode atau catatan dalam dokumen (atau bahkan pesan kesalahan dalam linter khusus) yang menunjukkan kepada pembaca apa yang perlu mereka ketahui. Anda dapat menulis komentar kecil dengan tautan ke tiket Jira yang menjelaskan mengapa kode ini diperlukan, atau Anda dapat memberi tahu orang-orang perintah mana yang harus dijalankan untuk memperbaiki bug. Remah roti sangat mudah ditambahkan ke dokumen dan menghemat banyak waktu.
Mengapa
Sangat mudah untuk lupa menulis tentang hal-hal yang tampak jelas. Tentu saja, bagaimana kami membuat layanan mikro, saya tidak perlu menulis mengapa kami melakukan ini. Tapi Anda perlu.
Ini jelas bagi Anda, tetapi tidak bagi pembaca. Alasan di balik keputusan itu tampak sangat jelas bagi kami karena kami telah menghabiskan begitu banyak waktu untuk memikirkannya.
Ketika Anda menjelaskan mengapa Anda melakukan sesuatu, Anda dipaksa untuk secara mental melacak langkah-langkah yang mengarah pada keputusan tersebut. Ternyata itu juga cara yang bagus untuk memperkenalkan Anda pada topik tertentu.
Jika Anda terjebak mencoba menjelaskan alasannya, bayangkan saja seperti apa dunia ini jika apa yang Anda dokumentasikan tiba-tiba menghilang. Siapa yang peduli dengan apa yang mereka lihat?
Lebih baik lagi jika Anda bisa menjelaskan alasannya dengan sebuah cerita. Orang-orang sangat pandai memproses dan mengingat cerita.
Saya suka komentar lain dalam dokumentasi. Sebagai contoh. "Kami tahu itu tidak bagus, dan kami benar-benar ingin itu berfungsi seperti X, tetapi itu akan membutuhkan tim T untuk memperbarui materi mereka, dan mereka sangat kewalahan, jadi kami menjalaninya untuk saat ini." Ini adalah jenis informasi yang menyatukan segala sesuatu di kepala orang dan membuat mereka merasa mengerti apa yang sedang terjadi.
Topik non-teknis
Hanya karena Anda mendokumentasikan topik teknis bukan berarti pembaca juga tidak perlu mengetahui beberapa hal non-teknis. Alasan kasus ini sangat serius.
Detail non-teknis berguna lainnya termasuk:
- , (, -, , ).
- . « X , Y, Z»
- . « , , , ».
- , « , ...»
Tutorial dimaksudkan untuk membiasakan orang dengan topik tersebut. Ini adalah cara yang sangat baik untuk melakukannya karena orang belajar lebih baik ketika mereka melakukan sesuatu, daripada hanya membaca.
Tutorial juga membutuhkan banyak investasi (dibandingkan dengan jenis dokumen lainnya). Menuliskannya mungkin hanya masuk akal jika banyak orang perlu mempelajari suatu topik. Jika hanya beberapa orang, bertemu mereka secara langsung (atau webcam ke webcam) mungkin merupakan penggunaan waktu terbaik.
Perangkap saat menulis tutorial adalah mencoba menjelaskan semuanya. Tahan keinginan untuk membuat daftar semua detail teknis dan semua pengecualian terhadap aturan yang ditetapkan. Anda hanya ingin pembaca Anda memahami mekanisme dasar. Detail kecil dapat ditinggalkan untuk dokumentasi bagi orang yang lebih berpengalaman.
Juga sangat sering tutorial tidak bekerja ketika seseorang mencoba untuk bekerja dengan mereka. Anda perlu mencoba langkah-langkah yang Anda tulis (idealnya di komputer baru tanpa semua komponen sudah terpasang) untuk memastikan semuanya lengkap dan benar-benar berfungsi. Kemudian ikuti langkah-langkah pada saat seseorang perlu menggunakan panduan ini dan lihat di mana mereka terjebak.
Langkah-langkahnya juga akan ketinggalan zaman, jadi pastikan untuk mendengarkan orang yang memiliki masalah dengannya.
Panduan
Panduan cenderung memberikan pengembalian investasi yang baik. Menghabiskan 10 menit untuk mendaftar langkah-langkah dalam daftar berpoin dapat menghemat satu jam untuk memikirkan apa yang harus dilakukan selanjutnya.
Ini sangat berharga ketika sulit untuk memahami apa langkah-langkah ini, atau jika langkah penting mudah dilewati.
Tulis panduan ketika Anda baru saja melalui proses dan termotivasi untuk menghindari memikirkan semuanya lagi.
Penjelasan dan Bantuan
Sejujurnya, saya tidak yakin tentang nilai dokumentasi referensi gaya javadoc. Tentu saja, jika satu juta orang akan menggunakan pelajaran Anda, singsingkan lengan baju Anda dan dokumentasikan semuanya hingga detail terkecil. Tetapi jika hanya tim Anda yang membaca, mereka sudah tahu 99% dari apa yang dapat Anda tulis.
Penjelasan umumnya lebih berguna, terutama ketika mereka fokus untuk menjelaskan alasannya. Jika Anda menjelaskan pengguna dan kendala teknis yang mengarah pada pembuatan desain, Anda hampir bisa melupakan menjelaskan desain itu sendiri - dipersenjatai dengan informasi latar belakang, seseorang dapat mengetahuinya sendiri dengan membaca kodenya. Anda dapat (akhirnya) mempelajari struktur hanya dengan membaca kode, tetapi sulit atau bahkan tidak mungkin untuk memahami alasannya dengan cara ini.
Praktek dokumentasi
Menulis dokumentasi membutuhkan waktu. Banyak waktu. Menghabiskan waktu untuk dokumentasi bukan hanya keajaiban karena seseorang berkata "kami membutuhkan lebih banyak dokumentasi." Anda harus menyisihkan waktu untuk ini dan menghabiskan berjam-jam menulis. Tidak, ini bukan cara paling menyenangkan untuk menghabiskan Kamis malam, tetapi Anda harus melakukannya.
Atau tidak? Anda hanya boleh menulis dokumentasi jika berguna. Anda tidak akan menulis kode hanya untuk menulis lebih banyak kode (atau mungkin Anda akan melakukannya, tetapi saya tidak akan melakukannya). Anda menulis kode untuk memecahkan masalah tertentu. Anda juga harus menulis dokumentasi untuk memecahkan masalah tertentu.
“Sesuatu” ini dapat diimplementasikan untuk membantu orang baru memberi energi pada tim, mengurangi faktor bus dalam tim, menghindari kesalahan karena lupa langkah, menghemat waktu orang saat melakukan tindakan, memberikan konteks, membangun kesepakatan, menulis kasar tetapi penting detail, dll. Jika Anda tidak tahu mengapa Anda menulis dokumentasi, jangan lakukan itu. Setelah Anda mengetahui alasannya, pilih dokumentasi yang sesuai untuk masalah yang sedang dipecahkan.
Tolong, atas nama semua yang suci, jangan menulis dokumentasi seperti ini:
/**
* @param customer The customer
* @param order The order
* @return The price
*/
public Price getPrice(Customer customer, Order order) {}
Ini tidak ada gunanya dan mengajarkan pembaca untuk melewatkan komentar secara mental. Mereka akan melewatkan komentar yang sebenarnya berisi sesuatu yang bermanfaat. Jika Anda tidak punya apa-apa untuk dikatakan, jangan katakan itu.
Dokumentasi, seperti kode, perlu dipelihara. Anda harus membayar untuk penyimpanannya. Anda harus meluangkan waktu untuk mendukungnya. Untungnya, ini biasanya jauh lebih murah daripada memelihara kode. Anda hanya perlu beberapa jam dalam sebulan untuk membaca seluruh wiki dan memperbaiki apa yang salah saat ini.
Tip: Buat bagian "arsip" di dokumentasi Anda dan pindahkan materi usang ke sana. Ini mempertahankan konteks sejarah, lebih baik daripada hanya menghapus dokumentasi, dan tidak perlu tertipu oleh pembaca yang tidak curiga.
Salah satu cara untuk menghemat waktu adalah dengan mengubah pekerjaan lain menjadi dokumentasi. Jika Anda perlu menjelaskan kepada rekan kerja cara mengintegrasikan dengan sistem Anda, salin apa yang Anda tulis di Slack ke dalam dokumen. Jika Anda menulis dokumentasi proyek, salin beberapa bagian ke dalam dokumentasi dan luangkan 10 menit untuk mempersiapkannya. Kapan pun Anda perlu menjelaskan sesuatu kepada pengulas dalam tinjauan kode, jelaskan dengan komentar dalam kode, bukan komit di Github. Apakah tiket Jira Anda menjelaskan mengapa tugas tersebut harus diselesaikan? Keren, salin ini dan Anda memiliki dokumentasinya. (Jika tidak, minta penanya untuk menuliskannya!)
Beri tahu orang-orang ke mana harus pergi untuk mengajukan pertanyaan. Untuk menulis “jika Anda memiliki pertanyaan, Anda dapat menghubungi kami di # saluran tim di Slack” dalam waktu sekitar 15 detik. Ini dapat menghemat waktu Anda jika Anda bingung. Pengembalian yang cukup bagus menurut saya
, jadi kopinya sudah habis, jadi saya akan berhenti di situ.