Kunci Membuat Dokumentasi Teknis Yang Baik

Kunci membuat dokumentasi yang baik adalah menganggap semua calon pembaca sebagai orang awam yang tidak tahu apa-apa. Kasarnya, anggap saja semua calon pembacanya bodoh & perlu dibimbing dengan jelas. Kunci kedua adalah memahami apa sih pertanyaan yang mungkin timbul ketika orang membaca dokumen kita. Kita harus bisa mengantisipasi munculnya pertanyaan “mengapa begini” & “mengapa begitu”. Bagaimana antisipasinya? Dengan menjelaskan latar belakang mengapa kita menuliskan sebuah statement.

Tentu kita masih perlu membatasi siapa calon pembaca dokumentasi yang kita buat. Tidak mungkin kita mengakomodasi semua orang dengan berbagai macam latar belakang pengetahuan. Ini memang bagian yang sangat “tricky” untuk menentukan siapa calon pembaca dokumentasi kita.

Misalkan saja kita akan membuat dokumentasi untuk staf di kantor tentang cara menambahkan printer pada Windows 7, lalu kita tulis dalam dokumentasi kita :

  1. Klik Windows Start menu dari pojok kiri bawah layar.
  2. Lalu klik Control Panel,
  3. Lalu klik Devices & Printers.

Sepintas terlihat sudah detil setiap langkahnya. Tapi apa yang terjadi bila user yang menggunakan dokumentasi kita belum familiar dengan Windows 7? Misalnya user akan komplain “Pak..di Control Panel tidak ada pilihan Devices & Printers“. Ternyata di Control Panel-nya Windows 7, Devices & Printers hanya keliatan bila kita pilih opsi “View by : Large Icon”.  Mungkin di komputer user yang bersangkutan opsi “View by” masih diset sebagai Category.

win7-printer

Langkah sepele yang rasanya perlu ditambahkan dalam dokumentasi untuk mengantisipasi kasus seperti itu.

Hal lain yang bisa menjadikan sebuah dokumentasi gampang dipahami adalah dengan memberikan contoh hasil yang diharapkan. Dalam dunia komputer misalnya, kita bisa menambahkan log hasil test kita sendiri atau mungkin dengan menambahkan screenshot apa yang kita lakukan. Dengan adanya contoh pembaca memiliki referensi sukses atau tidaknya dia mengikuti petunjuk yang dijelaskan dalam dokumentasi tadi. Akan lebih baik lagi jika kita juga menuliskan error apa yang kemungkinan didapatkan oleh user sewaktu mengerjakan apa yang kita tulis dalam dokumentasi kita.

Waktu saya bekerja di perusahaan Jepang, saya dapat pelajaran berharga tentang bagaimana pentingnya membuat dokumentasi yang baik. Baik dalam arti tersusun dengan sistematis, jelas sampai pada detil terkecil. Orang Jepang punya kebiasaan mencatat segala detil informasi. Tidak heran bila kita temui orang Jepang ke mana-mana mengantongi buku catatan kecil. Mereka seperti memiliki filosofi bahwa semua orang seperti robot, siapa pun yang memegang dokumentasi mereka akan bisa mengerjakan apa yang ditulis di sana.

Tips lain adalah menghindari penggunakan kalimat yang terlalu panjang. Dokumentasi yang baik tidak berarti menggunakan kalimat yang panjang dan bertele-tele. Tips ini menurut saya sifatnya universal, tidak hanya cocok untuk penulisan sebuah dokumentasi teknis. Memang tidak gampang membuat sebuah dokumentasi teknis yang bagus. Perlu extra waktu, extra tenaga & perlu kepekaan tersendiri. Kepekaan berkait juga dengan kepedulian jangan sampai pembacanya kebingungan. Mentalitas “asal saya ngerti” itulah yang menghalangi orang menghasilkan sebuah dokumentasi yang baik.

3 thoughts on “Kunci Membuat Dokumentasi Teknis Yang Baik

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.