Joel on Software

Joel on Software   Pojok Software Joel

 

Artikel-artikel "Joel on Software" lain dalam bahasa Indonesia

Artikel-artikel "Joel on Software" lain dalam bahasa Inggris

Email pengarang (hanya dalam bahasa Inggris)

 

Functional Specification yang Mudah - Part 4: Tips


Oleh Joel Spolsky
Diterjemahkan oleh Mas Agung Sachli
15 Oktober 2000

Baik, kita telah membicarakan tentang mengapa anda membutuhkan sebuah spec, apa yang dimiliki oleh spec, and siapa yang harus menulisnya. Ini merupkan bagian keempat dan terakhir dari seri ini. Saya akan membagikan beberapa nasehat untuk menulis spec yang bagus.

Keluhan terbesar yang anda akan dengar dari anggota tim bila menulis spec adalah: 'tidak ada yang membacanya". Saat tidak ada yang membaca spec, orang yang menulisnya akan cenderung sedikit sinis. Ini mirip dengan kartun Dilbert lama di mana engineer tersebut menggunakan specs setebal 4 inci untuk mengganjal cubicles mereka. Pada perusahaan anda yang besar dan birokratis seperti umumnya, setiap orang menghabiskan berbulan-bulan menulis specs yang membosankan. Saat spec tersebut selesai, langsung disimpan di rak, dan tidak pernah digunakan lagi, dan produknya diimplementasikan dari awal tanpa menghiraukan spec tersebut, karena tidak ada yang membaca spec, karena spec tsb sangat membosankan. Setiap proses penulisan spec merupakan sebuah latihan yang bagus, karena hal itu akan memaksa seseorang, setidaknya, berpikir tentang masalah tersebut. Namun kenyataannya bahwa spec disimpan (tidak dibaca dan disukai) setelah selesai membuat orang merasa itu hanya merupakan pekerjaan yang sia-sia.

Juga, jika spec anda tidak pernah dibaca, anda akan mendapatkan banyak argumentasi ketika produk yang telah selesai diserahkan. Orang lain (management, marketing, atau seorang customer) berkata: "tunggu sebentar! Anda menjanjikan saya akan ada sebuah Clam Steamer! Mana Clam Steamer-nya?" Dan programmer berkata, "tidak, sebetulnya, kalau anda melihat di spec bab 3, sub-bab 4, paragraf 2.3.01, anda akan lihat secara jelas bahwa 'tidak ada clam steamer". Namun hal itu tidak memuaskan customer, yang selalu benar, sehingga sambil menggerutu programmer tersebut harus menambahkan sebuah clam steamer ke dalamnya (membuat mereka semakin sinis terhadap spec). Atau seorang manager berkata, "hei, semua kalimat di dialog ini terlalu panjang, dan di sana juga harus ada iklan di bagian atas di semua kotak dialog". Dan programmer-nya dengan frustasi berkata, "namun anda telah menyetujui spec yang secara tepat menampilkan tataletak dan isi dari setiap kotak dialog!" Namun tentu saja, manager tersebut tidak betul-betul membaca spec tersebut, karena bila mereka mencoba, otak mereka akan mulai meleleh melalui rongga mata mereka dan lagi pula hal ini akan mengganggu jadwal main golf-nya di setiap hari Selasa.

Jadi. Spec sebenarnya bagus, namun tidak ada yang membacanya. Sebagai seorang penulis spec, anda harus memperdayakan orang agar membaca tulisan anda, dan anda mungkin harus berusaha agar tidak menyebabkan otak yang sudah kecil tersebut tidak meleleh melalui rongga mata.

Jurus agar orang membaca tulisan anda sebenarnya hanya masalah menulis dengan benar. Namun rasanya tidak adil kalau saya hanya mengatakan "jadi seorang penulis yang baik" dan hanya itu saja. Berikut empat aturan mudah yang harus anda ikuti agar spec anda dibaca.

Aturan No. 1: Melucu lah

Yep, peraturan nomor satu agar membuat orang membaca spec anda adalah membuat pengalaman tersebut menyenangkan. Jangan katakan pada saya bahwa anda tidak dilahirkan lucu, saya tidak percaya itu. Setiap orang mempunyai ide yang lucu setiap saat, mereka hanya menyensor diri sendiri karena mereka pikir hal tersebut "tidak profesional". Fuh.. Kadang kala anda perlu melanggar aturan tersebut.

Jika anda membaca sejumlah sampah yang telah saya tulis di web site ini, anda akan perhatikan bahwa bagaimana usaha saya untuk melucu sepanjang tulisan tersebut. Empat paragraph yang lalu saya melucu tentang lelucon tentang cairan tubuh yang menjijikkan dan melucu tentang manager yang bermain golf. Walaupun saya tidak begitu lucu, saya tetap berusaha keras, dan bahkan kelakuan konyol untuk berusaha menjadi lucu itu sendiri merupakan hal yang menghibur, dipandang dari cara seorang badut. Saat anda menulis sebuah spec, sebuah tempat yang mudah untuk melucu adalah di contoh. Setiap saat anda perlu menceritakan tentan bagaimana sebuah fitur bekerja, daripada menulis:

  • Pengguna mengetik Ctrl+N untuk membuat sebuah daftar karyawan yang baru dan mulai mengetik nama karyawan tersebut.

tulislah seperti ini:

  • Nona Piggy, menekan keyboard dengan sebuah pensil mata karena jari kecil nan gendutnya terlalu besar untuk menekan sebuah key, menekan Ctrl+N untuk membuat sebuah tabel teman lelaki baru dan mengetik sebuah record "Kermit."

Jika anda sering membaca Dave Barry, anda akan tahu bahwa hal yang termudah untuk melucu adalah menyebutkan sesuatu yang bukan dirinya secara spesifik. "Pudel nakal" akan lebih lucu dibandingkan "Anjing". "Nona Piggy" akan lebih lucu dari "user". Daripada menyebutkan "Orang tertentu", sebut saja "Petani alpukat yang kidal". Daripada mengatakan "Orang yang menolak membersihkan anjingnya harus dihukum", tulislah bahwa mereka harus di "kirim ke penjara yang sepi sehingga mereka harus membayar laba-laba untuk melakukan sex".

Oh, dan, ngomong-ngomong, jika anda pikir bahwa saya tidak profesional dengan melucu, maafkan saya, itu berarti anda tidak mempunyai selera humor. (Jangan sangkal. Orang yang tidak mempunyai rasa humor selalu menyangkalnya. Anda tidak dapat mebohongi saya). Dan jika anda bekerja di sebuah perusahaan yang tidak menghargai anda karena spec anda ringan, lucu dan menyenangkan untuk dibaca, carilah perusahaan lain untuk bekerja, karena hidup ini terlalu singkat untuk dihabiskan ditempat yang tidak menyenangkan seperti itu.

Aturan no. 2: Tulislah spec seperti menulis kode untuk di-eksekusi oleh otak

Berikut pendapat saya mengapa programer sulit menulis spec yang baik.

Saat anda menulis kode, pemirsa utama anda adalah compiler. Ya, saya tahu, orang juga harus membaca kode, namun hal tersebut umumnya sulit bagi mereka. Bagi kebanyakan programmer sudah cukup sulit untuk menghasilkan kode yang dapat dibaca secara tepat oleh compiler dan menerjemahkannya dengan benar. Memikirkan kode yang dapat dibaca oleh manusia akan lebih sulit lagi. Apakah anda menulis seperti:

void print_count( FILE* a, char  *  b, int c ){
    fprintf(a, "there are %d %s\n", c, b);}

main(){ int n; n =
10; print_count(stdout, "employees", n) /* code
deliberately obfuscated */ }

atau

printf("there are 10 employees\n");

anda akan mendapat hasil yang sama. Oleh sebab itu, jika anda pikirkan, anda cenderung melihat programmer menulis seperti ini:

Asumsikan sebuah fungsi AddressOf(x) yang didefinisikan sebagai pemetaan dari seorang user X, ke alamat email menurut RFC-822, sebuah string ANSI. Mari kita asumsikan user A dan user B, dimana A ingin mengirim email ke B. Jadi user A membuat berita baru dengan menggunakan salah satu (tidak semua) cara yang akan dijelaskan, dan mengetik AddressOf(B) di dalam editBox To:.

Seharusnya bisa ditulis seperti:

Nona Piggy ingin makan siang, sehingga dia membuat email baru dan menulis alamat Kermit di kotak "To:". 

Catatan Teknis: alamat tersebut harus mengikuti standard alamat internet (RFC-822 compliant.)

Keduanya mempunyai "arti" yang sama, secara teori, kecuali contoh pertama tersebut tidak mungkin dimengerti kecuali anda pelan-pelan mencernanya, dan contoh kedua lebih mudah untuk dimengerti. Programmer sering mencoba menulis spec yang mirip dengan tugas makalah sekolah. Mereka pikir bahwa sebuah spec yang "tepat" harus tepat secara "teknis" dan kemudian mereka lepas kendali.

Kesalahannya adalah saat anda menulis sebuah spec, selain harus tepat, juga harus dapat dimengerti, dalam istilah programming: bisa di-'compile' oleh otak manusia. Salah satu perbedaan mendasar antara komputer dan otak manusia adalah komputer bersedia duduk dengan sabarnya sementara anda mendefinisikan istilah yang anda pakai belakangan. Namun manusia tidak akan mengerti apa yang anda bicarakan kecuali anda menjelaskannya terlebih dahulu. Manusia tidak mau memproses sesuatu, mereka hanya ingin membaca hanya untuk mendapatkan pengertian. Bagi manusia, anda perlu memberikan gambaran besarnya baru kemudian detailnya. Dengan program komputer, anda mulai dari atas dan bekerja terus sampai ke bawah, dengan detail-detailnya. Sebuah komputer tidak perduli bila nama variable anda tidak punya arti. Otak seorang manusia akan lebih mengerti bila anda bisa melukiskan sebuah gambaran yang jelas dalam benak mereka melalui sebuah cerita, walaupun itu merupakan sepotong cerita, karena otak kita telah terbiasa dengan cerita.

Jika anda menunjukkan sebuah papan catur, di tengah-tengah permainan, kepada seorang pemain catur yang berpengalaman selama satu atau dua detik, mereka bisa dengan cepat mengingat semua posisi buah catur tersebut. Namun jika anda memindahkan beberapa buah catur ke posisi yang tidak mungkin terjadi pada permainan normal (contohnya: letakkan beberapa pion di baris pertama, atau letakkan dua peluncur hitam di kotak hitam), akan membuat mereka sangat sulit untuk mengingat posisi papan tersebut. Hal ini berbeda dengan komputer. Sebuah komputer yang dapat mengingat sebuah papan catur bisa mengingat sama mudahnya antara susunan yang mungkin dan tidak mungkin. Cara otak manusia bekerja bukan secara acak; alur pikiran cenderung memperkuat otak kita dan sesuatu hal lebih mudah dimengerti dibandingkan hal lainnya karena mereka lebih lazim.

Jadi, saat anda menulis sebuah spec, cobalah untuk membayangkan orang yang anda tuju, dan coba membayangkan apa yang anda ingin mereka mengerti setiap langkahnya. Kalimat per kalimat, tanyakan pada diri anda apakah orang yang membaca kalimat ini akan mengerti hal itu dengan mendalam, tentang apa yang anda katakan pada mereka. Jika beberapa anggota dari target audiens anda tidak mengetahui tentang RFC-822, anda perlu mendefinisikannya, atau, paling tidak, menguburkan penjelasan tentang RFC-822 di bagian catatan teknis, sehingga orang non teknis yang membaca spec tersebut tidak akan menyerah dan berhenti membaca saat mereka melihat begitu banyaknya istilah teknis.

Aturan No. 3: Tulis sesederhana mungkin

Jangan gunakan bahasa formal yang kaku hanya karena anda pikir tidaklah profesional jika menulis dalam kalimat yang sederhana. Gunakan bahasa paling sederhana yang anda bisa. 

Orang suka menggunakan kata "utilize" karena mereka pikir kata "use" kelihatannya tidak profesional. (Muncul kata 'tidak profesional' lagi. Lain kali bila ada orang yang mengatakan kepada anda bahwa anda sebaiknya jangan melakukan sesuatu karena itu tidak 'profesional', anda tahu bahwa mereka telah kehabisan argumentasi yang nyata.) Malahan saya pikir ada banyak orang yang mengira bahwa menulis yang jelas merupakan sesuatu yang salah.

Bagi menjadi beberapa kalimat pendek. Jika anda kesulitan untuk menulis sebuah kalimat yang jelas, bagi kalimat tersebut menjadi dua atau tiga kalimat yang lebih pendek. 

Hindari tembok huruf: seluruh halaman hanya berisi tulisan saja. Orang akan segan dan tidak membaca tulisan anda. Kapan terakhir kali anda membaca sebuah majalah yang populer dengan seluruh halamannya berisi text? Majalah bisa hidup sedemikian lamanya karena mereka mengutip dari artikel dan menampilkannya di tengah-tengah halaman, dengan font raksasa, hanya untuk menghindari sebuah halaman penuh dengan tulisan. Gunakan daftar bernomor atau bertanda, gambar, tabel, dan banyak tempat kosong sehingga membacanya lebih menyenangkan.

             

 

"Majalah bisa hidup sedemikian lamanya karena mereka mengutip dari artikel dan menampilkannya di tengah-tengah halaman, dengan font raksasa, hanya untuk menghindari sebuah halaman penuh dengan tulisan."


 

 

Tiada yang memperbaiki sebuah spec lebih baik dibandingkan cuplikan layar yang banyak. Sebuah gambar bisa bermakna seribu kata. Siapa pun yang menulis specs untuk software Windows harus berinvestasi dalam satu copy Visual basic, dan belajar menggunakannya paling tidak cukup baik untuk membuat layar tiruan. (Untuk Mac, gunakan REAL Basic; untuk halaman Web, gunakan Front Page atau Dreamweaver). Lalu tangkap layar tersebut (Ctrl+PrtSc) dan paste ke dalam spec anda.

Aturan No. 4: Review dan baca ulang beberapa kali

Hmm, saya sebenarnya berencana menjelaskan aturan ini dengan panjang lebar, namun aturan ini terlalu sederhana dan jelas. Review dan baca ulang spec anda beberapa kali, OK? Bila anda menemukan kalimat yang tidak luar biasa mudah untuk dimengerti, tulis ulang.

Saya telah menghemat banyak waktu untuk tidak menjelaskan aturan 4 ini sehingga saya akan menambahkan aturan yang lain.

Aturan No.5: Templates dianggap berbahaya

Hindari godaan untuk membuat sebuah template standard untuk specs. Pada awalnya anda mungkin terpikir adalah hal yang penting untuk menyamakan tampilan semua spec. Jawabannya: tidak. Perbedaan apa yang akan terjadi? Apakah semua buku pada rak buku di rumah anda kelihatan sama persis? Apakah anda tetap menginginkannya?

Parahnya lagi, jika anda mempunyai template, yang cenderung terjadi adalah anda menambahkan sekumpulan bagian yang anda pikir penting untuk semua fitur. Contoh: Si Big Bill menyatakan bahwa mulai saat ini, setiap produk Microsquish harus mempunyai sebuah komponen internet. Jadi template spec sekarang mempunyai sebuah bagian yang bernama "Komponen Internet". Saat seseorang menulis sebuah spec, tidak perdulu seberapa mudahnya, mereka harus mengisi bagian yang bernama "Komponen Internet" tersebut, bahkan jika anda hanya membuat sebuah spec untuk keyboard Microsquish. (Dan anda heran mengapa tombol internet yang tidak berguna tersebut mulai bermunculan seperti jamur di keyboard).

Seiring dengan bertambahnya bagian tersebut, templatenya semakin menjadi besar. (Ini ada contoh sebuah template yang sangat-sangat buruk untuk spec. Ya ampun, siapa yang butuh bibliography atau Glossary di sebuah spec? Masalah dengan template yang besar ini adalah hal itu akan menakutkan orang untuk menulis specs karena kelihatannya seperti tugas yang menakutkan.

Spec adalah sebuah dokumen yang anda inginkan orang lain baca. Oleh sebab itu, tidak ada bedanya dengan sebuah essay di The New Yorker atau makalah kuliah. Pernahkah anda mendengar seorang dosen membagikan template untuk muridnya untuk membuat makalah? Pernahkah anda membaca dua buah essay yang bagus yang bisa masuk ke dalam satu template? Lupakan ide tersebut.



Artikel ini aslinya bahasa Inggris dengan judul Painless Functional Specifications Part 4  

Joel Spolsky adalah pendiri Fog Creek Software, sebuah perusahaan software kecil di New York City. Dia lulus dari Yale University, dan pernah bekerja sebagai programer dan manajer di Microsoft, Viacom, dan Juno.


Isi halaman-halaman ini mewakili opini dari satu orang.
Semua isi Hak Cipta ©1999-2005  dari Joel Spolsky. Hak Cipta dilindungi Undang-undang

FogBUGZ | CityDesk | Fog Creek Software | Joel Spolsky