Kamis, 11 September 2014
DOKUMENTASI
SOFTWARE
 
Rangkuman dan Terjemahan dari sumber :
Software Documentation
Ian Sommerville
Lancaster University, UK

Dokumentasi Software

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.

II. 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 dimanajemen
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.

II.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 seharihari
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.

II.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.

II.2.1. User Documentation
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
Untuk memenuhi kebutuhan berbagai macam user beserta keahliannya yang masing-masing
berbeda, paling tidak ada 5 macam dokumen yang harus diikutsertakan dalam penyerahan suatu
produk software/sistem :

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.


II.2.2. System Documentation
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.  
 






















III. 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.

III.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 seberapapun 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.



























III.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.

III.2.1. 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.

III.2.2. 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
dll.

3. Document presentation standards
Mengatur style tampilan dari dokumen, termasuk di dalamnya jenis huruf yang
digunakan, cover, pewarnaan, penggunaan logo dan nama perusahaan dll.

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.

III.2.3. 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.

III.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

III.4.Dokumentasi On-Line
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
dokument 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 mengkateforikan / 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.


IV. 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 yg 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.

0 komentar:

Posting Komentar

The Alien - Help Select