Untuk Menulis Technical Writing dengan Baik, Anda Perlu Menurunkan Ekspektasi [Artikel Terjemahan]

1. Menulis adalah keterampilan wajib bagi engineer

   • Penulisan teknis sangat penting bagi engineer di semua level, mulai dari commit message hingga dokumentasi.
   • Perbedaan antara menulis dengan baik dan tidak berdampak besar pada efisiensi kerja dan komunikasi dalam organisasi.

2. Sebisa mungkin ringkas dan singkat

   • Pembaca tidak akan menghabiskan banyak waktu untuk sebuah tulisan.
   • Jika sebuah ide bisa disampaikan dalam satu kalimat, lakukanlah.
   • Sengaja menghilangkan sebagian detail justru bisa menjadi kelebihan.
   • Letakkan hal yang penting di bagian awal tulisan, pada kalimat pertama atau judul.

3. Tetapkan ekspektasi secara realistis

   • Jangan berharap orang akan membaca tulisan teknis dengan teliti dan memahaminya sepenuhnya.
   • Dalam organisasi engineering, kebingungan dan perbedaan tingkat pemahaman adalah hal yang normal, dan tulisan tidak bisa membuat semua orang menjadi sama.
   • Dengan menurunkan ekspektasi, komunikasi justru bisa menjadi lebih efektif.

4. Tujuan tulisan adalah menyampaikan inti dengan jelas

   • Prioritas utama adalah menyampaikan poin yang sangat sederhana kepada tim yang luas, seperti “menambahkan konfigurasi itu rumit”.
   • Daripada mendorong pemahaman teknis yang sepenuhnya lengkap, lebih penting memberi konteks minimum yang menumbuhkan kepercayaan.

5. Efek yang benar-benar bisa diharapkan

   • Penerima tulisan pada umumnya memiliki pengetahuan latar yang lebih sedikit dibanding penulisnya.
   • Untuk audiens yang luas, yang mungkin adalah penyampaian pesan sederhana; untuk segelintir orang, penyampaian jelas atas hal yang kompleks.
   • Hanya dengan menyoroti inti saja pun sudah membuat perbedaan besar dalam organisasi berskala besar.

6. Pikiran yang jelas menghasilkan tulisan yang jelas

   • Topik yang belum cukup dipahami sulit untuk dipadatkan.
   • Akui ketidakpastian, dan fokuslah pada bagian yang bisa dijelaskan dengan jelas.

7. Kesalahan dan hal yang disarankan

   • Jangan terlalu terobsesi menyampaikan terlalu banyak detail.
   • Ringkaslah isi yang ingin disampaikan secara bertahap menjadi satu kalimat, satu paragraf, lalu satu halaman, dan sampaikan inti terlebih dahulu.
   • Bahkan bagi orang yang hampir tidak memiliki latar teknis, menyampaikan konteks besarnya sendiri sudah bernilai.

[yeobi222]

Bagian yang paling saya pikirkan adalah bagaimana memasukkan penjelasan tambahan agar pembaca bisa memahami.
Ketika pengambil keputusan adalah orang yang awam di bidang tersebut, atau...

[girr311]

Ini tampaknya berlaku bukan hanya untuk dokumentasi teknis, tetapi juga untuk sebagian besar dokumen.