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.
Demikian, Semoga Bermanfaat
