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.

Belajar Tensis Lagi

Dari dulu saya tidak pernah mengambil kursus bahasa Inggris. Saya kenal bahasa Inggris hanya di sekolah, sejak SMP saya dapat pelajaran bahasa Inggris. Salah satu pelajaran yang tidak saya suka…bingung ga ngerti. Meskipun nilai pelajaran bahasa Inggris saya bagus, paling tidak 8, kemampuan bahasa Inggris saya benar-benar pas-pasan. Jangankan untuk bercakap-cakap dalam bahasa Inggris, menulis dalam bahasa Inggris pun tidak bisa. Benar-benar nilai yang tidak realistis, hanya sebatas saya mampu mengerjakan soal ulangan bahasa Inggris.

Menginjak bangku kuliah saya terkondisikan mengerti bahasa Inggris lebih jauh lagi. Mau tidak mau saya harus melatih kemampuan membaca teks bahasa Inggris karena buku-buku kuliah hampir semuanya dalam bahasa Inggris. Buku kuliah teknik elektro dalam bahasa Indonesia malah sulit dipahami karena keterbatasan penerjemahan. Ya sudah mau tidak mau saya harus belajar artikel bahasa Inggris. Buku teknik yang ditulis dalam bahasa Inggris menurut saya lebih mudah untuk dipahami. Jangan bandingkan dengan koran berbahasa Inggris seperti The Jakarta Post, rumit…pusing saya baca koran berbahasa Inggris ๐Ÿ˜€ Saya juga pernah beli novel Sherlock Holmes dalam bahasa Inggris, sampai sekarang saya hanya baca 1 bab saja….selebihnya buku novel itu jadi tatakan harddisk PC saya ๐Ÿ˜€ Iseng saja beli novel luar negri karena tertarik dengan kualitas kertasnya yang super ringan, bukunya ringan sekali.

Waktu wawancara kerja pertama kali di Jakarta Agustus 2006 lalu, saya masih ingat mantan bos saya dulu bilang : kamu harus meningkatkan kemampuan bahasa Inggrismu ๐Ÿ™‚ Ya pertama kali interview ditanya dalam bahasa Inggris, saya 100% gagap. Untungnya interview pertama itu sebagian besar dilakukan dalam Bahasa Indonesia. Hanya 1 sesi saja mantan bos saya itu menguji kemampuan bahasa Inggris saya. Jelek bahasa Inggrisnya pun bisa tembus diterima kerja. Interview berikutnya sekitar April 2007 hampir separuhnya dilakukan dalam bahasa Inggris. Halah….untung saya sudah lebih pede bercakap-cakap dalam bahasa Inggris. Kuncinya cuma pede saja…modal nekat, kalimat berantakan tak masalah, yang penting keyword-nya sudah bisa ditangkap oleh lawan bicara :)) Saat interview di Fujitsu, semua yang mewawancarai saya adalah orang Indonesia. Interview terakhir di kantor saya sekarang dilakukan dalam bahasa Inggris semua. Bos saya orang Perancis, mau tidak mau harus ngomong dalam bahasa Inggris…lah masa mau ngomong bahasa Perancis :-p Belakangan saya makin sering menggunakan bahasa Inggris, yang paling sering dipakai adalah bahasa Inggris tulisan…menulis email terutama. Makin banyak pula kesempatan bercakap-cakap dalam bahasa Inggris karena tidak sedikit rekan kantor yang berkebangsaan asing. Sudah fasih berbahasa Inggris? Ya belum sih…karena terpaksa saja jadi bisa.

Beberapa kali saya juga mencoba menulis postingan di blog dalam bahasa Inggris….ya itung-itung latihan menulis lah. Bukan gaya-gayaan sok kebarat-baratan. Beberapa hari yang lalu teman saya, Jennifer, sempat mengoreksi beberapa kesalahan dalam postingan yang saya buat dalam bahasa Inggris. Banyak untungnya punya teman yang fasih beberapa bahasa sekaligus, seperti kamus online saja ๐Ÿ˜€ Kalau lihat kamus sudah tidak menemukan clue, tinggal tanya Jennifer via Yahoo Messenger (kalau ybs. online juga tentunya). Kesalahan yang terbanyak adalah soal tenses. Ya salah satu kelemahan saya dalam bahasa Inggris adalah soal Tenses. Rasa-rasanya belajar Tenses secara langsung dengan Jennifer lebih bisa dipahami daripada beberapa tahun dapat pelajaran bahasa Inggris di sekolah. Saya jadi lebih paham bedanya penggunaan was/were, has/have, verbs 3. Dari obrolan panjang lebar saya diberi 4 rumus dewa soal Tenses, berikut kutipan hasil chat dengan Jennifer :

(10:43:07 PM) Jennifer: semua yg pake continues pasti ada to be nya
(10:43:18 PM) Jennifer: semua yg pake perfect pasti ada has have nya
(10:43:47 PM) Jennifer: kl ada to be, berarti V ing
(10:43:54 PM) Jennifer: kl ada has have berarti V3

(10:48:51 PM) Tedy: was + V-ing berarti waktu itu melakukan sesuatu
(10:49:03 PM) Jennifer: yap, sedang melakukan
(10:49:09 PM) Tedy: kl was + V3 berarti waktu itu DI-apa-KAN ๐Ÿ˜€
(10:49:26 PM) Jennifer: betul, pasif

Ah benar-benar menyenangkan belajar seperti ini, langsung mengena rasanya…lebih ngeh saya memahaminya. Mungkin karena hal-hal semacam itu kerap kali saya gunakan saat menulis dalam bahasa Inggris. Belajar sesuatu yang memang kita butuhkan rasanya lebih cepat dipahami daripada sekadar belajar sesuatu karena kewajiban. Buktinya soal Tenses itu kan sebenarnya kan sudah pernah saya dapat di bangku SMP/SMA, tapi mengapa saya masih kesulitan menggunakannya? Jawabannya adalah karena dulu saya belajar sekadar memenuhi kewajiban, tidak untuk diterapkan/digunakan sehari-hari. Seiring sejalan saya merasa perlu tahu dan paham soal Tenses. Tadinya saya pikir cukup untuk tahu banyak vocabulary (kosa kata Inggris) tapi ternyata sehari-hari dalam penulisan email misalnya, Tenses penting juga diperhatikan.

Beberapa minggu lalu saya sempat dapat hasil fotokopi ‘Effective Guide to “O” Level English‘ (seperti Anda lihat di foto). Buku yang bagus juga sebagai sumber referensi saya mengulang materi soal Tenses dalam Bahasa Inggris. Waktunya belajar sungguh-sungguh lagi soal Tenses dan penggunaannya. Paling tidak membuat saya menulis lebih baik lagi, syukur-syukur kalau bisa menggunakannya secara tepat dalam percakapan. Kemarin saya sudah mulai baca buku itu, bab 1-nya ternyata berisi soal Tenses…tepat seperti apa yang ingin saya pelajari ๐Ÿ˜€ Selain Tenses, saya juga sepertinya perlu menambah lagi kosa kata irregullar verbs…kadang bingung menentukan bentuk lampau dari kata kerja tertentu. Yang lebih sulit dilatih sebenarnya bukan soal Tenses, yang lebih sulit dilatih adalah kemampuan percakapan dalam bahasa Inggris (conversation). Kadang saya masih sering terbalik-balik menggunakan “she” untuk menyebut laki-laki dan malah menyebut “he” untuk perempuan =)) Tahu tapi sulit ngomongnya; otak & lidah gak sinkron :))

Wibsite atau Website

Tadi pagi saya sempat mengambil beberapa foto di depan depan rumah. Ada yang menempel selebaran iklan di depan kos. Iklannya tentang pelatihan bisnis internet. Tadinya saya tidak melihat yang spesial atau unik dari foto selebaran tadi. Setelah memindahkan foto dari ke dalam komputer, saya kembali mengamati foto-foto tersebut termasuk foto iklan tadi. Ternyata saya menemukan beberapa hal yang unik di selebaran iklan tersebut ๐Ÿ˜€

Foto besarnya seperti berikut ini :

Salah satu keunikannya adalah di bagian ini :

Entah apakah yang mengetik iklan tersebut memang salah ketik atau memang tidak tahu cara menuliskan website :-p Lucu rasanya melihat istilah “wibsite” di iklan itu. Sebenarnya ada kesalahan ketik lainnya di iklan tersebut. Misalnya “sistem” ditulis “siatem”, lalu “bisnis” malah diketik “bisisnis”.

He..he..he…maafkan saya yang usil ini ๐Ÿ˜€

Blade On the Heart

Anda yang membaca tulisan ini dan mengerti bahasa Mandarin pasti tahu apa arti karakter/huruf di samping ini. Jadi ceritanya kemarin rekan saya Joni memberi nasihat yang bagus untuk saya. Dia bilang ada 1 huruf China yang cocok untuk saya…huruf persis yang ada pada gambar di samping ini. Huruf itu adalah huruf ren katanya dibaca “jen“, bingung juga bagaimana menulis huruf ‘e’ dengan ‘topi’ di atasnya. Dalam bahasa Mandarin kalau tidak salah ada 4 macam suara (satu tulisan dengan 4 cara pengucapan, masing-masing punya arti sendiri). Secara literal, huruf ‘ren’ tersebut berarti pedang yang menancap di hati. Huruf ‘ren’ tersebut terdiri dari 2 kata. Bagian yang atas (yang berbentuk seperti M, berarti pedang), sementara bagian yang bawah (yang terlihat seperti W, berarti hati). Kamus Mandarin online Zhongwen (dibaca “cung wen”) menjelaskan kata ‘ren‘ artinya “blade in the heart” ๐Ÿ˜ฎ

Dalam konteks nasihat Joni pada saya, ‘ren’ diartikan sebagai menahan diri. Huruf-huruf atau kata dalam bahasa Mandarin memang penuh dengan filosofi. Sebuah kata dapat terbentuk dari gabungan beberapa kata, dengan gabungan tersebut terbentuk sebuah makna baru. Memang hebat kebudayaan China itu, pantas diacungi jempol kebudayaan mereka sudah maju sekian abad sebelum Masehi dan penuh dengan ajaran filosofi.

Ya kemarin Joni memang sedang menasihati saya soal “menahan diri”. Awalnya kita sedang bicara soal menabung. Orang yang boros seperti saya memang layak dinasihati untuk menabung ;)) . Pesan moral yang saya dapat mungkin artinya lebih baik menahan diri dulu untuk kebaikan saya di masa depan. Mulai belajar menabung (diikuti hidup hemat tentunya) memang tidak mudah. Apa yang dimaksud dalam kata ren tadi mungkin bisa menggambarkan bagaimana sulitnya mulai menabung. Mengekang keinginan, belajar bersabar, menahan diri tidak konsumtif, bukan sesuatu yang gampang bahkan bisa menyakitkan (tapi bukan sesuatu yang mustahil). Menurut kamus Zhongwen kata ‘ren’ juga dapat diartikan sebagai endure (sabar). Ah memang keren huruf Mandarin yang satu ini…dalam artinya. Tiap kali mulai tidak sabaran, tiap kali mulai tidak bisa menahan diri, tinggal ingat saja ada pedang yang menancap di hati…terasa sakit tapi harus tetap bertahan.

Nah tadi sempat mikir juga bagaimana cara mengetik aksara Mandarin di Ubuntu. Dulu saya sempat menulis tentang bagaimana menulis aksara kanji/Mandarin di Windows, tulisan itu ada di sini. Googling sebentar sampai bertemu dengan panduan ini. Saya ringkas langkahnya seperti berikut ini :

  1. Instal paket-paket berikut ini :
    tedy-laptop:/# sudo apt-get install scim-qtimm im-switch scim-pinyin
    
  2. Atur cara input dengan perintahย im-switch :
    tedy-laptop:/ # im-switch -z all_ALL -s scim
    
  3. Logoff dulu dari Ubuntu, setelah login kembali Anda akan menjumpai icon bebentuk keyboard di bagian notification bar (di Ubuntu by default ada di bagian kanan atas layar).
  4. Klik icon tersebut lalu pilih Chinese Simplified untuk mulai mengetik aksara Mandarin. Untuk balik lagi ke mode teks biasa silakan pilih English Keyboard. Gambar huruf di atas saya ketik di OpenOffice.

Jangan terlalu percaya pada penjelasan saya soal huruf Mandarin & cara pengucapannya…lah wong saya gak bisa bahasa Mandarin kok ;)) Saya cuma terkesan saja dengan huruf Mandarin yang itu. Tapi Anda boleh percaya pada penjelasan saya tadi soal bagaimana mengetik aksara Mandarin di komputer berbasis Linux ๐Ÿ˜€ Tambahan informasi, di situs ini Anda bisa lihat bagaimana cara menulis karakter Mandarin (garis demi garis tidak boleh salah urutannya).

Thanks Pak Jon buat nasihatnya kemarin

Apa Yang Salah?

Coba Anda perhatikan foto di bawah ini :

Melihat sesuatu yang ganjil? Menangkap ada yang salah?

Belum melihat ada yang salah pada foto di atas? Hmm ulangi lagi deh, lihat baik-baik ๐Ÿ˜€

Sudah dapat? Masih belum juga? Coba kunjungi optik terdekat untuk memeriksakan mata Anda :))

Foto di atas adalah foto kardus wadah speaker merek Simbadda. Ada kesalahan cetak pada kardus tempat speaker itu. Tulisan “Powdr input -ac 220V” seharusnya kan “Power input -ac 220V”. Astaga rupanya Simbadda selaku produsen kurang memperhatikan detail pada kemasan produknya. Di mata saya kok sepintas terbaca “Powder :-/

Jadi ceritanya hari Rabu kemarin salah satu rekan kantor saya akan pulang kampung ke Rumania.ย  Dia menitipkan sound system dan DVD player-nya pada saya. Sejak saya ambil dari apartemennya hari Rabu lalu, belum saya sentuh-sentuh lagi sampai malam ini. Malam ini saya utak-atik speaker-nya…nah saya baru sadar ternyata ada yang salah di kardus tempat speaker itu. Salah cetak, mungkin bukan salah cetak tapi salah ketik :-p

nahTadi saya ingin coba speaker Simbadda itu untuk disambungkan dengan notebook. Sekadar ingin membandingkan kualitas suaranya dengan speaker milik saya sendiri. Dilihat dari spesifikasinya, Altec Lansing saya lebih powerfull. Tapi ternyata speaker tersebut bukan speaker untuk PC. Tidak ada colokan standar untuk PC ๐Ÿ˜ฎ , colokan yang ada cuma yang bentuknya seperti ini :

Ah tapi terpikir oleh saya cocok juga colokan macam itu disambungkan dengan televisi di kamar. Alhasil saya sambungkan output decoder Indovision saya ke speaker ini. Lumayan “bum bum bum” suaranya untuk nonton TV ;))