Pendahuluan
Semua proyek pengembangan software profesional, menghasilkan sejumlah dokumentasi yang tidak kecil. Oleh karena itu, manajer dan software engineer harus memperhatikan permasalahan dokumentasi dan biaya-biaya yang timbul karenanya, disamping pengembangan software itu sendiri.Dokumen-dokumen yang berkaitan dengan proyek software dan sistem yang dikembangkan memiliki beberapa persyaratan:
1. Harus bisa menjadi media komunikasi antara anggota-anggota tim pengembang
2. Harus bisa menjadi gudang informasi tentang sistem yang dapat dipergunakan untuk kepentingan maintenance.
3. Harus bisa menyediakan informasi bagi manajemen yang dapat membantu dalam membuat perencanaan, pembiayaan dan penjadwalan dalam proses pengembangan software
4. Harus bisa memberitahu user bagaimana cara menggunakan dan mengoperasikan sistem tersebut.
Software engineer yang biasanya bertanggungjawab atas pembuatan hampir semua jenis dokumentasi yang ada pada pengembangan software walaupun kadang dibantu oleh penulis teknis profesional untuk memoles dokumen sebelum dirilis.
Di sini akan dijelaskan beberapa tipe dokumen yang mungkin ada dalam proyek pembuatan/pengembangan software, lalu pentingnya kualitas dari dokumen yang dihasilkan dan struktur, standar serta gaya penulisan yang tepat untuk suatu dokumen.
Dokumentasi Proses dan Dokumentasi Produk
Pada proyek software yang besar, beberapa dokumen biasanya telah dihasilkan bahkan sebelum proses pengembangan/pembuatan dimulai. Seperti adanya proposal untuk pembuatan sistem/software tertentu sebagai jawaban dari permintaan klien ataupun strategi bisnis. Berikutnya adalah dokumen requirement yang komprehensif yang mendefinisikan fitur-fitur yang dibutuhkan atau perilaku sistem yang diharapkan dari suatu sistem.
Selama proses pengembangan sendiri, ada banyak jenis dokumen yang dapat dihasilkan, rencana proyek, spesifikasi desain, rencana pengetesan, dan lain-lain. Beberapa dokumen yang diproduksi dalam proyek dapat dikategorikan dalam 2 kelas yang berbeda:
1. Dokumentasi proses; Dokumen-dokumen ini merekam proses pengembangan dan maintenance. Rencana-rencana, jadwal-jadwal, dokumen kualitas proses, standar organisasi dan standar proses merupakan dokumentasi proses.
2. Dokumentasi produk; Dokumentasi ini menggambarkan produk yang sedang dikembangkan. Dokumentasi sistem menjelaskan produk dari sudut pandang teknis dalam mengembangkan dan memelihara sistem. Dokumentasi user menyediakan penjelasan produk yang berorientasi pada user.
Dokumentasi proses dibuat agar pengembangan suatu sistem/software dapat di manajemen dengan baik. Dokumentasi produk digunakan setelah sistem/software selesai atau operasional tetapi juga dapat berguna bagi manajemen proses pengembangan sistem, dalam kasus perbaikan atau revisi suatu sistem/software.
1. Dokumentasi Proses
Agar manajemen dapat efektif, dibutuhkan suatu kejelasan pada proses-proses yang akan dikelola. Karena software merupakan suatu hal yang non fisik dan proses pembuatan software juga merupakan tugas-tugas pemikiran yang tidak terlihat fisik, salah satu cara agar membuat jadi jelas adalah dengan menggunakan dokumentasi.
Ada beberapa kategori dokumentasi proses:
1. Perencanaan, perkiraan dan penjadwalan. Merupakan dokumen yang dibuat oleh manajer yang digunakan untuk memprediksi dan mengontrol proses software.
2. Laporan / Reports . Merupakan dokumen yang mencatat bagaimana sumber dayasumber daya digunakan selama proses pengembangan.
3. Standar. Dokumen – dokumen ini menentukan bagaimana seharusnya suatu proses diimplementasikan. Ada berbagai macam standar mulai dalam lingkup organisasi, nasional bahkan internasional.
4. Lembar kerja/ working paper. Sering kali merupakan dokumen komunikasi teknis utama dalam suatu proyek. Mereka merekam ide-ide dan pikiran-pikiran para engineer yang bekerja dalam proyek, yang merupakan dokumentasi produk versi sementara yang menjelaskan strategi pengimplementasian dan penentuan masalah yang telah diidentifikasi. Seringkali dokumen ini mencatat alasan-alasan pemilihan suatu keputusan dalam desain.
5. Memo dan surat/pesan elektronik. Dokumen yang merekam rincian komunikasi sehari-hari antara manajer dan development engineer.
Karakteristik utama dari dokumentasi proses adalah hampir semuanya akan menjadi kadaluarsa. Banyak informasi yang akan menjadi tidak berguna apabila telah terlewati dan normalnya tidak ada kepentingan untuk tetap menyimpannya setelah sistem/software telah jadi, seperti jadwal / perencanaan pembuatan. Bagaimanapun juga tetap ada beberapa dokumentasi proses yang berguna apabila ada perubahan software yang diinginkan, seperti hasil testing dan lembar kerja yang mencatat alasan-alasan kenapa suatu desain dipilih dalam pembuatan suatu sistem.
2. Dokumentasi Produk
Dokumentasi produk berkenaan dengan gambaran suatu produk software/sistem yang telah jadi. Tidak seperti dokumentasi proses, dokumentasi produk biasanya berguna untuk waktu yang lebih lama, selama produk tersebut masih digunakan. Dokumentasi produk melingkupi user documentation yang memberitahu pengguna bagaimana cara mengoperasikan produk software, dan system documentation yang utamanya diperuntukkan bagi teknisi maintenance.
Pengguna dari suatu software/sistem tidaklah dapat disamaratakan. Merupakan suatu hal yang penting untuk membedakan antara end-user dengan system administrator.
1. End-user menggunakan software sebagai alat bantu untuk mengerjakan suatu tugas, menulis sebuah buku, mengelola keuangan, bahkan menerbangkan pesawat. Mereka ingin tahu seberapa software dapat memudahkan pekerjaan mereka tetapi tidak ingin tahu detail teknis tentang software tersebut.
2. System administrator bertanggung jawab mengelola dan memelihara software yang digunakan oleh end-user. Dapat berupa operator, network manager, hingga master teknis yang memecahkan segala permasalahan end-user berkaitan dengan software, atau juga penghubung antara user dengan software developer.
 |
| Gambar 1. Tipe-tipe User Documentation |
1. Functional description of software/system
- Secara singkat menggambarkan kebutuhan sistem untuk menjalankan program
- Servis-servis yang dimiliki (fitur2) aplikasi
- Gambaran umum dr aplikasi (abstraksi)
- User dapat menentukan apakah aplikasi benar-benar dibutuhkan hanya dengan membaca functional description dan introductory manual.
2. The system installation document
- Diperuntukan bagi system administrator.
- Menyediakan informasi mendetail bagaimana cara menginstall system di lingkungan system yang spesifik.
- Mencantumkan gambaran file-file apa yang membentuk suatu sistem/aplikasi.
- Persyaratan minimum dari hardware yang dibutuhkan.
- File-file(aplikasi) yang harus ada sebelum sistem diinstall
- Cara memulai system/aplikasi
- Cara mengkonfigurasi aplikasi agar berjalan dengan system yang telah ada
- Adanya installer otomatis untuk aplikasi-aplikasi sekarang membuat para pembuat S/W memandang tidak perlu adanya dokumen ini, padahal pada kenyataannya dokumen instalasi ini masih dibutuhkan agar para System manager dapat menemukan dan memecahkan sumber masalah jika ada problem pada waktu instalasi.
3. The introductory manual
- Menyediakan pengenalan tentang system/aplikasi yang menggambarkan fungsi/penggunaan umum dari system/aplikasi tersebut.
- Menjelaskan cara memulai menggunakan program
- Menjelaskan bagaimana para user dapat menggunakan fungsi-fungsi umum yang dimiliki aplikasi disertai ilustrasi dan contoh bebas.
- Mencantumkan kesalahan-kesalahan yang umum/sering dilakukan oleh user dan cara menyelesaikannya.
4. The system reference manual
- Menjelaskan semua kegunaan dan fungsi yang dimiliki system/aplikasi
- Mencantumkan semua pesan kesalahan yang dimiliki sistem dan cara mengatasinya secara lengkap dan detail
- Penggunaan bahasa resmi dan teknik bisa digunakan
- Mencantumkan secara lengkap fitur dan cara operasional dari system/aplikasi
5. System administrator guide
- Installation + system reference manual.
System Documentation mencakup semua gambaran sistem itu sendiri mulai dari spesifikasi kebutuhan hingga hasil pengetesan yang dapat diterima (final acceptance test plan). Dokumen-dokumen yang menggambarkan bagaimana desain, implementasi dan pengetesan suatu sistem merupakan dokumen penting untuk bisa memahami dan memaintain software tersebut.
Untuk suatu sistem besar yang dikembangkan dalam rangka memenuhi spesifikasi kebutuhan dari pelanggan, sistem documentation harus mencakup:
1. Dokumen yang mencatat kebutuhan pelanggan dan alasan-alasannya.
2. Dokumen yang menggambarkan arsitektur dari sistem
3. Untuk setiap program yang ada pada sistem, gambaran arsitektur dari program tersebut.
4. Untuk setiap komponen sistem, gambaran dari fungsionalitas/kegunaan dan interfaceinterfacenya.
5. Listing kode program. Harus disertai komentar-komentar yang dapat menjelaskan bagian-bagian program yang kompleks beserta alasan penggunaan metode pengkodean tersebut. Apabila penamaan yang baik dan struktur pemrograman yang baik telah digunakan, listing kode tersebut akan lebih mudah dipahami tanpa memerlukan komentar tambahan.
6. Dokumen validasi. Menjelaskan bagaimana setiap program divalidasi dan kaitannya dengan spesifikasi kebutuhan yang diinginkan oleh pelanggan.
7. Panduan sistem maintenance, yang menjelaskan permasalahan-permasalahan yang telah diketahui dapat terjadi pada sistem.
 |
| Gambar 2. Klasifikasi dokumentasi software / system |
Kualitas Dokumen
Banyak sekali dokumentasi sistem komputer ditulis dengan kualitas yang rendah, yaitu sulit dimengerti, out of date dan tidak lengkap. Kualitas dokumen merupakan hal yang sama pentingnya dengan kualitas software. Tanpa adanya informasi bagaimana suatu software dapat digunakan atau dipahami, kegunaan suatu software akan menurun. Untuk mendapatkan dokumentasi yang berkualitas dibutuhkan komitmen pada desain dokumen, standar dan proses penjaminan kualitas. Membuat dokumen yang baik tidak mudah dan murah, serta banyak software engineer yang kesulitan untuk membuat dokumentasi yang berkualitas.
1. Struktur Dokumen
Struktur dokumen adalah suatu cara di mana materi dalam dokumen diorganisasikan dalam bab-bab, sub bab – sub bab, dan sub sub bab – sub sub bab. Struktur dokumen memiliki dampak yang besar dalam daya guna dokumen dan sangat penting untuk didesain terlebih dahulu dalam pembuatan suatu dokumen. Sama seperti sistem software, kita harus mendesain struktur dokumen sedemikian rupa sehingga bagian-bagian yang berbeda benar –benar independent. Sehingga setiap bagian dapat dibaca sebagai item tunggal secara terpisah.
Struktur dokumen yang baik dan benar juga dapat memudahkan pembaca untuk mencari informasi yang benar-benar diperlukan. Berdasarkan standar IEEE untuk user documentation, struktur dokumentasi sebaiknya memiliki komponen-komponen antara lain:
a. Identifikasi data; data seperti judul dan identifier dapat mengidentifikasikan dokumen secara unik.
b. Daftar isi; berisi nama bab/sub bab dan nomor halaman.
c. Daftar Ilustrasi; berisi nomor ilustrasi dan nomor halamannya.
d. Introduction/pengantar; menjelaskan tujuan dari dokumen dan ringkasan singkat tentang isi dari dokumen.
e. Informasi penggunaan dokumen; saran bagi berbagai macam pembaca tentang bagaimana menggunakan dokumen secara efektif.
f. Konsep operasi; penjelasan latarbelakang konseptual untuk menggunakan software.
g. Prosedur; petunjuk penggunaan software.
h. Informasi perintah dalam software; penjelasan tiap perintah yang ada pada software.
i. Pesan kesalahan dan pemecahannya; penjelasan bagaimana suatu error/kesalahan yang dapat terjadi pada program ditampilkan dan bagaimana cara mengatasinya.
j. Glossary; definisi dari penggunaan istilah khusus.
k. Sumber informasi terkait; referensi ke dokumen lain yang dapat menyediakan informasi tambahan
l. Fitur navigasi; fitur yang dapat digunakan pembaca lokasi yang sedang dibaca dan bagaimana berpindah ke bagian lain dari dokumen.
m. Index; daftar kata-kata kunci dan halaman dimana kata tersebut dipakai.
n. Kemampuan pencarian; pada dokumen elektronik /digital , suatu cara mencari kata yang digunakan dalam dokumen.
Dari berbagai macam metode strukturisasi dokumen, ada pedoman minimal dalam struktur dokumen yang sebaiknya diikuti:
1. Semua dokumen, tidak peduli seberapa pun banyaknya, harus memiliki halaman kover yang mengidentifikasikan proyek, nama dan jenis dokumen, pengarang, tanggal pembuatan dokumen, informasi penjaminan kualitas, peruntukan dokumen dan tingkat kerahasiaan dokumen.
2. Dokumen yang lebih dari beberapa halaman, harus dibagi menjadi bab-bab dan sub bab. Memiliki daftar isi, menggunakan penomoran bab dan sub bab yang konsisten. Setiap bab memiliki penomoran halaman terpisah, sehingga memudahkan apabila ada perubahan di salah satu bab saja, tidak perlu melakukan perubahan nomor halaman di keseluruhan dokumen.
3. Apabila dokumen memiliki banyak penjelasan detil, informasi referensi harus diberi index.
4. Apabila dokumen diperuntukkan pembaca yang memungkinkan pengetahuannya berbeda, glossary perlu ditambahkan untuk menjelaskan istilah-istilah teknis dan akronim yang digunakan di dokumen.
Struktur dokumen sering kali ditentukan di awal dan dimasukkan dalam standar dokumentasi. Hal ini memudahkan dalam konsistensi pembuatan dokumen dalam suatu proyek.
 |
| Gambar 3. Contoh halaman kover dokumen |
2. Standar Dokumen
Standar dokumen merupakan dasar untuk melakukan penjaminan kualitas suatu dokumen. Dokumen yang dibuat berdasarkan standar yang benar akan memiliki tampilan, struktur dan kualitas yang konsisten. Standar yang digunakan pada proses dokumentasi adalah:
1. Standar proses. Mendefinisikan proses yang harus diikuti untuk menghasilkan dokumen yang berkualitas tinggi.
2. Standar produk. Standar yang mengatur dokumen itu sendiri.
3. Standar pertukaran / interchange standards. Merupakan hal yang penting untuk dapat bertukar dokumen melalui email dan menyimpannya dalam suatu database. Standar pertukaran menjaga agar setiap dokumen dapat kompatibel.
a. Standar Proses
Standar proses mengatur pendekatan / metode yang harus dilakukan dalam membuat suatu dokumen. Secara umum hal ini biasanya dengan menentukan software yang digunakan dalam menulis suatu dokumen dan prosedur penjaminan kualitas yang dapat dilakukan untuk mengukur kualitas dokumen yang dihasilkan.
Standar penjaminan kualitas dokumen harus fleksibel dan dapat mencakup semua tipe dokumen yang ada dalam proyek. Dalam beberapa kasus memang tidak perlu diterapkan standar penjaminan kualitas dokumen, seperti pada dokumen lembar kerja atau memo.
b. Standar Produk
Produk standar berlaku untuk semua dokumen yang diproduksi oleh pengembang software. Dokumen harus memiliki tampilan yang konsisten, dan setiap jenis/kategori dokumen harus memiliki struktur yang konsisten.
Beberapa standar yang seharusnya diperhatikan :
1. Document Identification standard
Proyek-proyek besar biasanya memproduksi sampai ribuan dokumen. Setiap dokumen harus memiliki identifikasi yang unik yang mengikuti aturan yang ditetapkan organisasi.
2. Document structure standard
Setiap kategori dokumen yang dihasilkan suatu organisasi harus memiliki struktur yang tetap/konsisten yang telah ditetapkan. Termasuk didalam struktur dokumen adalah penggunaan format penomoran halaman, header dan footer, penomoran bab dan sub-bab dan lain-lain.
3. Document presentation standards
Mengatur style tampilan dari dokumen, termasuk di dalamnya jenis huruf yang digunakan, cover, pewarnaan, penggunaan logo dan nama perusahaan dan lain-lain.
4. Document update standards
Dokumen dapat berubah dalam perkembangannya, cara yang konsisten dalam suatu update harus diatur dalam suatu proses dokumentasi. Perubahan harus teridentifikasi dan tercatat, penggunaan versi harus ada untuk mengetahui sejarah perubahan.
c. Interchange Standar
Standar pertukaran dokumen semakin penting seiring dengan semakin banyaknya dokumentasi yang dibuat dalam format elektronik / digital selain dengan media cetak atau kertas.
Pembuatan dokumen elektronik menggunakan Adobe Portable Document Format (PDF) semakin umum digunakan. Bagaimanapun juga, pertukaran dokumen antar anggota tim pengembang dalam satu organisasi/perusahaan sering kali menggunakan format word processor umum (Microsoft Word atau Open Office Word).
Dengan asumsi penggunaan standar dari word processor atau graphic editor telah ditentukan pada standar proses, yang ditentukan dalam standar pertukaran adalah konvensi/kaidah-kaidah yang harus digunakan dalam penulisan dokumen menggunakan word processor atau graphic editor tersebut. Seperti logo/simbol tertentu untuk menyatakan suatu hal, pembatasan font, penggunaan style tertentu dalam word processor, dan penggunaan macro standar.
3. Gaya Penulisan
Secara umum, untuk menghasilkan dokumentasi yang berkualitas, beberapa pedoman dalam gaya penulisan dokumen yang dapat diikuti adalah sebagai berikut :
1. Penggunaan kalimat aktif
2. Penggunaan tata bahasa dan ejaan yang tepat
3. Kurangi kalimat-kalimat yang panjang
4. Kurangi paragraf yang panjang
5. Tidak bertele-tele
6. Gunakan dan definisikan istilah secara tepat
7. Ulangi penjelasan untuk hal yang rumit dengan bahasan yang berbeda
8. Gunakan judul bab dan sub bab
9. Menggunakan bullets/items dibanding penjelasan dengan kalimat
10. Tidak mereferensikan informasi hanya dengan nomer referensi saja
4. Dokumentasi Online
Saat ini sudah banyak ditemui pemberian dokumentasi online bersama-sama dengan pelepasan suatu produk sistem/software. Dokumentasi online tersebut bisa dalam bentuk file ‘read me’ yang berisi informasi terbatas dan sederhana, sampai dalam bentuk dokumentasi interaktif berbasis hypertext yang menginformasikan secara lengkap segala sesuatu tentang software yang bersangkutan. Yang paling umum dijumpai tentang dokumentasi online suatu software adalah dalam bentuk sistem bantuan berbasis hypertext.
Keuntungan utama penggunaan dokumentasi online tentunya adalah dari sisi aksesibilitas/kemudahan akses informasi. User tidak perlu lagi mencari-cari dokumen yang tepat untuk mencari informasi, menghilangkan kemungkinan mengambil dokumen yang tidak up-to-date, dan kalau ada fasilitas pencarian bisa digunakan untuk menemukan informasi yang tepat dalam waktu yang cepat. Bagaimanapun ada beberapa kerugian pada sistem dokumentasi hypertext sehingga seharusnya mereka tidak sepenuhnya mengganti dokumen cetak, tetapi cukup sebagai pelengkap dokumen cetak. Antara lain karena pada sistem dokumentasi hypertext:
- Tidak memiliki kemudahan pembacaan, sehingga pembaca tidak gampang membaca sepintas keseluruhan isi dokumen untuk mencari informasi yang dicari. Karena pembaca sering kali mempunyai kesulitan untuk mengkategorikan/mengkarakterisasi informasi yang mereka inginkan dari suatu dokumentasi, walaupun pada saat menemukannya /membacanya mereka tahu bahwa informasi itulah yang mereka cari. Pembacaan sepintas terhadap keseluruhan dokumentasi adalah mekanisme kunci untuk solusi pembaca yang seperti ini, bahkan seringkali secara kebetulan pembaca juga menemukan fasilitas lain dari software yang juga dapat mereka gunakan dengan cara pembacaan sepintas tapi menyeluruh seperti ini.
- Menggunakan layar monitor/lcd, yang memiliki resolusi yang lebih rendah bila dibandingkan dengan dokumentasi cetak/fisik. Pembaca juga seringkali merasakan kesulitan dan cepat lelah bila membaca secara online.
- Pembaca sering kali ‘tersesat’ dalam sistem dokumentasi berbasis hypertext, tanpa ada navigasi sistem yang jelas.
Oleh karena itu pada saat kita mendesain suatu dokumentasi online, harus memperhatikan permasalahan-permasalahan tersebut di atas. Walaupun dokumentasi cetak dan online sama-sama harus memperhatikan penulisan, desain yang untuk dokumentasi cetak dan online harus berbeda. Karena perbedaan karakteristik yang dibutuhkan untuk dokumentasi cetak dan online, konversi sederhana dari dokumen yang dibuat dalam word processor ke dalam bentuk HTML jarang sekali langsung menghasilkan dokumentasi online berkualitas tinggi.
Persiapan Dokumen
Persiapan Dokumen adalah suatu proses pembuatan dokumen dan proses pemformatan dokumen tersebut untuk publikasi. Pada gambar 4 dapat dilihat proses persiapan dokumen yang dibagi menjadi 3 tahap: pembuatan dokumen (document creation), penyempurnaan (polishing), dan produksi (production).
 |
| Gambar 4. Proses Persiapan Dokumen |
Software word processing yang modern saat ini sudah banyak yang menyediakan perangkat lengkap untuk menyelesaikan keseluruhan proses tersebut. Tetapi untuk menghasilkan kualitas tertinggi dari suatu dokumen, sebaiknya kita tidak hanya menggunakan satu software saja untuk menyelesaikan keseluruhan tahap dalam proses persiapan dokumen.
Tahap-tahap proses persiapan dokumen dibagi menjadi 3, yaitu:
1. Document creation.
Merupakan masukan informasi awal pada dokumen. Bisa dilakukan dengan menggunakan word processor, table and equation processor, drawing and art packages.
2. Document polishing.
Proses yang melakukan perbaikan dalam penulisan dan penampilan suatu dokumen agar menjadi lebih mudah dimengerti dan dibaca. Melibatkan proses perbaikan kesalahan tulis dan tata bahasa, pencarian frase-frase yang janggal, dan penghapusan perulangan teks yang tidak perlu. Bisa dilakukan dengan software online dictionaries, spelling checker, grammar and style checker.
3. Document production
Merupakan proses yang mempersiapkan dokumen untuk siap dicetak secara profesional.
Penulis: Arief Prasetyo
Share On
No comments:
Post a Comment