Tugas Kelompok

Teknik Dokumentasi
Dokumentasi Software

MI-1F

Disusun oleh :
1. Annisa Nabila Putri NIM / No abs : 2131710016 / 05
2. Muhammad Al Kindy NIM / No abs : 2131710057 / 14
3. Niken Maharani Permata NIM / No abs : 2131710006 / 19
4. Rivaldito Ilham Pratama NIM / No abs : 2131710146 / 21

POLITEKNIK NEGERI MALANG

MALANG
2021
 Pengantar
Semua proyek pengembangan perangkat lunak besar, apa pun aplikasinya,
menghasilkan sejumlah besar dokumentasi terkait. Untuk sistem berukuran sedang,
dokumentasi mungkin akan mengisi beberapa lemari arsip; untuk sistem besar, mungkin
mengisi beberapa ruangan. Sebagian besar biaya proses perangkat lunak dikeluarkan dalam
memproduksi dokumentasi ini. Selain itu, kesalahan dan kelalaian dokumentasi dapat
menyebabkan kesalahan oleh pengguna akhir dan kegagalan sistem yang diakibatkannya
dengan biaya dan gangguan yang terkait. Oleh karena itu, manajer dan insinyur perangkat lunak
harus memberikan banyak perhatian pada dokumentasi dan biaya yang terkait dengan
pengembangan perangkat lunak itu sendiri.
Dokumen yang terkait dengan proyek perangkat lunak dan sistem yang sedang
dikembangkan memiliki sejumlah persyaratan terkait:
1. Mereka harus bertindak sebagai media komunikasi antara anggota tim pengembangan.
2. Mereka harus menjadi tempat penyimpanan informasi sistem yang akan digunakan oleh
teknisi pemeliharaan.
3. Mereka harus menyediakan informasi bagi manajemen untuk membantu mereka
merencanakan, menganggarkan, dan menjadwalkan proses pengembangan perangkat
lunak.
4. Beberapa dokumen harus memberitahu pengguna bagaimana menggunakan dan
mengelola sistem.
Pemenuhan persyaratan ini memerlukan berbagai jenis dokumen dari dokumen kerja
informal hingga manual pengguna yang diproduksi secara profesional. Insinyur perangkat
lunak biasanya bertanggung jawab untuk memproduksi sebagian besar dokumentasi ini
meskipun penulis teknis profesional dapat membantu dengan pemolesan akhir informasi yang
dirilis secara eksternal.
Tujuan lampiran ini adalah untuk menjelaskan dokumentasi yang mungkin dihasilkan
selama proses perangkat lunak, untuk memberikan beberapa petunjuk tentang cara menulis
dokumen yang efektif dan untuk menggambarkan proses yang terlibat dalam pembuatan
dokumen-dokumen ini. Saya mulai dengan membahas berbagai jenis dokumentasi yang
mungkin dihasilkan dalam proyek perangkat lunak. Saya kemudian membahas topik penting
tentang kualitas dokumen dan membahas struktur dokumen, standar dokumentasi dan gaya
penulisan yang efektif. Terakhir, saya membahas proses persiapan, produksi, dan pengelolaan
dokumen.
 Fokus dalam makalah ini adalah pada dokumentasi yang dimaksudkan untuk dicetak dan
disampaikan di atas kertas atau dalam format seperti PDF yang dapat dilihat di layar atau
dicetak secara lokal. Banyak sistem sekarang juga memiliki sistem bantuan hypertext terkait.
Memproduksi sistem ini memerlukan seperangkat keterampilan yang berbeda dari membuat
dokumentasi kertas dan saya hanya membahasnya secara singkat di sini.

Dokumentasi Proses dan Produk

Dalam proyek perangkat lunak skala besar, biasanya dokumentasi mulai dibuat jauh
sebelum proses pengembangan dimulai. Proposal (dalam hal ini untuk mengembangkan
sistem) dapat dibuat sebagai jawaban atas permintaan tender oleh klien eksternal (pihak luar)
atau sebagai jawaban terhadap dokumen strategi bisnis lainnya. Untuk beberapa jenis sistem,
persyaratan dokumen yang komprehensif dapat diproduksi yang mendefinisikan fitur yang
diperlukan dan perilaku yang diharapkan dari sistem. Selama proses pengembangan itu sendiri,
semua jenis dokumen yang berbeda dapat dihasilkan – rencana proyek, spesifikasi desain,
rencana pengujian, dll.
Hal yang tidak mungkin untuk menentukan gabungan dokumen spesifik yang diperlukan -
ini tergantung pada kontrak dengan klien mengenai sistem, jenis sistem yang dikembangkan
dan masa pakai yang diharapkan, budaya dan ukuran perusahaan yang mengembangkan sistem
dan jadwal pengembangan yang diharapkan. Namun, secara umum kita dapat mengatakan
bahwa dokumentasi yang dihasilkan terbagi dalam dua kelas:
1. Dokumentasi proses
Dokumen-dokumen ini mencatat proses pengembangan dan pemeliharaan.
Rencana, jadwal, dokumen kualitas proses, dan standar organisasi serta proyek adalah
dokumentasi proses.
2. Dokumentasi produk
Dokumentasi ini menjelaskan produk yang sedang dikembangkan.
Dokumentasi sistem menjelaskan produk dari sudut pandang para insinyur yang
mengembangkan dan memelihara sistem, seperti dokumentasi pengguna memberikan
deskripsi produk yang berorientasi pada pengguna sistem.
Dokumentasi proses dibuat agar pengembangan sistem dapat dikelola. Dokumentasi produk
digunakan setelah sistem beroperasi tetapi juga penting untuk manajemen pengembangan
sistem. Pembuatan dokumen, seperti spesifikasi sistem, dapat mewakili tonggak penting dalam
proses pengembangan perangkat lunak.

Dokumentasi Proses

Manajemen yang efektif membutuhkan proses yang dikelola agar tampak kasat mata.
Karena perangkat lunak tidak berwujud dan proses perangkat lunak melibatkan tugas kognitif
yang tampaknya serupa dibandingkan tugas fisik yang jelas berbeda, satu-satunya cara
mencapai agar proses ini dapat dilihat dan diamati ini adalah melalui penggunaan dokumentasi
proses.
Dokumentasi proses terbagi dalam beberapa kategori:
1. Rencana, perkiraan dan jadwal
Ini adalah dokumen yang dihasilkan oleh manajer yang digunakan untuk memprediksi
dan mengontrol proses perangkat lunak.
2. Laporan
Ini adalah dokumen yang melaporkan bagaimana sumber daya digunakan selama
proses pengembangan.
3. Standar
Ini adalah dokumen yang menjelaskan bagaimana proses akan dilaksanakan. Bagian ini
dapat dikembangkan dari standar organisasi, nasional atau internasional.
4. Kertas kerja
Seringnya, ini merupakan dokumen komunikasi teknis utama dalam sebuah proyek.
Kertas kerja mencatat ide dan pemikiran para insinyur yang mengerjakan proyek,
merupakan versi sementara dari dokumentasi produk, menjelaskan strategi
implementasi dan menetapkan masalah yang telah diidentifikasi. Secara implisit
mereka sering mencatat dasar pemikiran untuk keputusan desain.
5. Memo dan pesan surat elektronik
Pada bagian ini mencatat rincian komunikasi sehari-hari antara manajer dan insinyur
pengembangan.
 Karakteristik utama dari dokumentasi proses adalah bahwa sebagian besar dari
dokumen menjadi usang / tidak dapat digunakan lagi. Rencana dapat dibuat setiap minggu,
setiap dua minggu atau setiap bulan. Kemajuan biasanya akan dilaporkan setiap minggu. Memo
mencatat pikiran, ide,dan niat yang berubah.
Meskipun menarik bagi sejarawan perangkat lunak, banyak dari informasi proses ini
tidak banyak digunakan setelah ketinggalan zaman dan biasanya tidak perlu untuk
melestarikannya setelah sistem dikirimkan. Namun, ada beberapa dokumen proses yang dapat
berguna saat perangkat lunak berkembang dalam menanggapi kebutuhan baru.
Misalnya, jadwal pengujian merupakan hal yang bernilai selama evolusi perangkat
lunak karena mereka bertindak sebagai dasar untuk merencanakan ulang validasi perubahan
sistem. Kertas kerja yang menjelaskan alasan di balik keputusan desain (rasionalisasi desain)
juga berpotensi berharga karena membahas opsi desain dan pilihan yang dibuat. Akses ke
informasi ini membantu menghindari membuat perubahan yang bertentangan dengan
keputusan awal ini. Idealnya, tentu saja, alasan desain harus diambil dari kertas kerja dan
dipelihara secara terpisah. Sayangnya ini hampir tidak pernah terjadi.

Dokumentasi Produk
Dokumentasi produk berkaitan dengan penggambaran produk perangkat lunak yang
dikirimkan. Tidak seperti kebanyakan dokumentasi proses, ia memiliki umur yang relatif
panjang. Dokumentasi produk harus berkembang sejalan dengan produk yang dijelaskannya.
Dokumentasi produk mencakup dokumentasi pengguna yang memberi tahu pengguna cara
menggunakan produk perangkat lunak dan dokumentasi sistem yang terutama ditujukan untuk
teknisi pemeliharaan.

Dokumentasi Pengguna
Pengguna suatu sistem tidak semuanya sama. Produser dokumentasi harus menyusunnya
untuk memenuhi tugas pengguna yang berbeda dan tingkat keahlian dan pengalaman yang
berbeda. Sangat penting untuk membedakan antara pengguna akhir dan administrator
sistem:
1. Pengguna akhir menggunakan perangkat lunak untuk membantu beberapa tugas.
Contohnya mungkin menerbangkan pesawat, mengelola polis asuransi, menulis
buku, dll. Mereka ingin tahu bagaimana perangkat lunak dapat membantu mereka.
Mereka tidak tertarik pada detail komputer atau administrasi
 2. Administrator sistem bertanggung jawab untuk mengelola perangkat lunak yang
digunakan oleh pengguna akhir. Ini mungkin melibatkan tindakan sebagai operator jika
sistem adalah sistem mainframe besar, berperan sebagai manajer jaringan jika sistem
melibatkan jaringan workstation atau berperan sebagai guru teknis yang memperbaiki
masalah perangkat lunak pengguna akhir dan yang menjadi penghubung antara
pengguna dan pemasok perangkat lunak.
Untuk memenuhi kelas pengguna yang berbeda dan tingkat keahlian pengguna yang
berbeda ini, setidaknya ada 5 dokumen (atau mungkin bab dalam satu dokumen) yang harus
dikirimkan dengan sistem perangkat lunak (Gambar 1).

Gambar 1 : Berbagai jenis dokumentasi pengguna

Pada deskripsi fungsional sistem menguraikan persyaratan sistem dan menjelaskan secara
singkat layanan yang disediakan. Dokumen ini harus memberikan gambaran umum tentang
sistem. Pengguna harus dapat membaca dokumen ini dengan manual pengantar dan
memutuskan apakah system sesuai dengan yang mereka butuhkan.
Pada dokumen instalasi sistem ditujukan untuk administrator sistem. Ini harus memberikan
rincian tentang cara menginstal sistem di lingkungan tertentu. Ini harus berisi deskripsi file
yang membentuk sistem dan konfigurasi perangkat keras minimal yang diperlukan. File
permanen yang harus dibuat, cara memulai sistem dan file tergantung konfigurasi yang harus
diubah untuk menyesuaikan sistem dengan sistem host tertentu juga harus dijelaskan.
Penggunaan penginstal otomatis untuk perangkat lunak PC berarti bahwa beberapa pemasok
menganggap dokumen ini tidak perlu. Bahkan, masih diperlukan untuk membantu manajer
sistem menemukan dan memperbaiki masalah dengan penginstalan.
 Pada panduan pengantar harus menyajikan pengantar informal ke sistem, menjelaskan
penggunaan 'normal'. Ini harus menjelaskan bagaimana memulai dan bagaimana pengguna
akhir dapat menggunakan fasilitas sistem umum. Itu harus diilustrasikan secara bebas dengan
contoh-contoh. Mau tidak mau pemula, apapun latar belakang dan pengalamannya, akan
melakukan kesalahan. Informasi yang mudah ditemukan tentang cara memulihkan dari
kesalahan ini dan memulai kembali pekerjaan yang bermanfaat harus menjadi bagian integral
dari dokumen ini.
Pada manual referensi sistem harus menjelaskan fasilitas sistem dan penggunaannya, harus
memberikan daftar lengkap pesan kesalahan dan harus menjelaskan bagaimana memulihkan
dari kesalahan yang terdeteksi. Bagian ini harus lengkap. Teknik deskriptif formal dapat
digunakan. Gaya manual referensi tidak boleh terlalu bertele-tele, tetapi kelengkapan lebih
penting daripada keterbacaan.
Panduan administrator sistem yang lebih umum harus disediakan untuk beberapa jenis
sistem seperti sistem komando dan system kontrol. Bagian ini harus menjelaskan pesan yang
dihasilkan ketika sistem berinteraksi dengan sistem lain dan bagaimana bereaksi terhadap
pesan ini. Jika perangkat keras sistem terlibat, mungkin juga menjelaskan tugas operator dalam
memelihara perangkat keras tersebut. Misalnya, ini mungkin menjelaskan cara menghapus
kesalahan di konsol sistem, cara menghubungkan periferal baru, dll.
Selain manual, dokumentasi lain yang mudah digunakan mungkin disediakan. Kartu
referensi cepat yang mencantumkan fasilitas sistem yang tersedia dan cara menggunakannya
sangat nyaman bagi pengguna sistem yang berpengalaman. Sistem bantuan online, yang berisi
informasi singkat tentang sistem, dapat menghemat waktu pengguna dalam konsultasi manual
meskipun tidak harus dilihat sebagai pengganti dokumentasi yang lebih komprehensif. Saya
secara singkat membahas dokumentasi online di bagian selanjutnya dalam makalah ini.

Dokumentasi Sistem

Dokumentasi sistem mencakup semua dokumen yang menjelaskan sistem itu sendiri dari
spesifikasi persyaratan hingga rencana uji penerimaan akhir. Dokumen yang menjelaskan
desain, implementasi, dan pengujian sistem sangat penting jika program ingin dipahami dan
dipelihara. Seperti dokumentasi pengguna, dokumentasi sistem harus terstruktur, dengan
tinjauan umum yang mengarahkan pembaca ke deskripsi yang lebih formal dan terperinci dari
setiap aspek sistem. Untuk sistem besar yang dikembangkan sesuai spesifikasi pelanggan,
dokumentasi sistem harus mencakup:
 1. Dokumen persyaratan dan alasan terkait.
2. Sebuah dokumen yang menjelaskan arsitektur sistem.
3. Untuk setiap program dalam sistem, deskripsi arsitektur program tersebut.
4. Untuk setiap komponen dalam sistem, deskripsi dari fungsionalitas dan antarmukanya.
5. Daftar kode sumber program. Bagian ini harus dikomentari di mana komentar harus
menjelaskan bagian kode yang kompleks dan memberikan alasan untuk metode
pengkodean yang digunakan. Jika nama yang bermakna digunakan dan gaya
pemrograman terstruktur yang baik digunakan, sebagian besar kode harus
didokumentasikan sendiri tanpa perlu komentar tambahan. Informasi ini sekarang
biasanya disimpan secara elektronik daripada di atas kertas dengan informasi pilihan
yang dicetak sesuai permintaan dari pembaca.
6. Dokumen validasi menjelaskan bagaimana setiap program divalidasi dan bagaimana
informasi validasi terkait dengan persyaratan.
7. Panduan pemeliharaan sistem menjelaskan masalah yang diketahui dengan sistem,
menjelaskan bagian mana dari sistem yang bergantung pada perangkat keras dan
perangkat lunak, dan yang menjelaskan bagaimana evolusi sistem telah diperhitungkan
dalam desainnya.

Masalah umum pemeliharaan sistem adalah memastikan bahwa semua representasi ikut
maju ketika sistem diubah. Untuk membantu hal ini, hubungan dan ketergantungan antara
dokumen dan bagian dokumen harus dicatat dalam sistem manajemen dokumen seperti yang
dibahas di bagian akhir makalah ini.
Untuk sistem yang lebih kecil dan sistem yang dikembangkan sebagai produk perangkat
lunak, dokumentasi sistem biasanya kurang komprehensif. Ini belum tentu merupakan hal yang
baik tetapi tekanan jadwal pada pengembang berarti bahwa dokumen tidak pernah ditulis atau,
jika ditulis, tidak diperbarui. Tekanan-tekanan ini terkadang tidak dapat dihindari tetapi,
menurut penulis, setidaknya Anda harus selalu berusaha mempertahankan spesifikasi sistem,
dokumen desain arsitektur, dan kode sumber program.
Sayangnya, pemeliharaan dokumentasi sering diabaikan. Dokumentasi dapat menjadi tidak
sesuai dengan perangkat lunak yang terkait, menyebabkan masalah bagi pengguna dan
pengelola sistem. Kecenderungan alami adalah untuk memenuhi tenggat waktu dengan
memodifikasi kode dengan tujuan memodifikasi dokumen lain di kemudian hari.
Seringkali, tekanan pekerjaan membuat modifikasi ini terus-menerus dikesampingkan
sampai menemukan apa yang akan diubah menjadi sangat sulit. Solusi terbaik untuk masalah
ini adalah untuk mendukung pemeliharaan dokumen dengan perangkat lunak yang mencatat
hubungan dokumen, mengingatkan insinyur perangkat lunak ketika perubahan pada satu
dokumen mempengaruhi yang lain dan mencatat kemungkinan inkonsistensi dalam
dokumentasi. Sistem seperti ini dijelaskan oleh Garg dan Scacchi (1990).

Kualitas Dokumen
Sayangnya, banyak dokumentasi sistem komputer ditulis dengan buruk, sulit untuk dipahami,
ketinggalan zaman atau tidak lengkap. Meski kondisinya membaik, banyak organisasi masih
kurang memperhatikan sistem produksi dokumen yang merupakan potongan prosa teknis yang
ditulis dengan baik. Kualitas dokumen sama pentingnya dengan kualitas program. Tanpa
informasi tentang bagaimana menggunakan suatu sistem atau bagaimana memahaminya,
kegunaan dari sistem itu adalah terdegradasi.
Mencapai kualitas dokumen memerlukan komitmen manajemen untuk desain dokumen,
standar, dan proses penjaminan mutu. Menghasilkan yang baik dokumen tidak mudah atau
murah dan banyak insinyur perangkat lunak merasa lebih banyak sulit yang menghasilkan
program berkualitas baik.

Struktur dokumen
Struktur dokumen adalah cara di mana materi dalam dokumen itu disusun dalam bab-bab dan,
di dalam bab-bab ini, menjadi bagian dan subbagian. Struktur dokumen memiliki dampak besar
pada keterbacaan dan kegunaan. Berikut komponen yang dianjurkan ada :
Data Identifikasi: Data seperti gelar dan pengenal yang unik
mengidentifikasi dokumen.
1. Daftar isi : Nama bab/bagian dan nomor halaman.
2. Daftar ilustrasi : Nomor gambar dan judul
3. Pendahuluan : Mendefinisikan tujuan dari dokumen dan ringkasan ringkasan
isinya
 4. Informasi untuk penggunaan dokumentasi : Saran untuk pembaca yang berbeda
tentang cara menggunakan dokumentasi secara efektif.
5. Konsep operasi : Penjelasan tentang latar belakang konseptual penggunaan
perangkat lunak.
6. Prosedur : Petunjuk tentang cara menggunakan perangkat lunak untuk
menyelesaikan tugas-tugas yang dirancang untuk mendukungnya.
7. Informasi tentang perangkat lunak : perintah Deskripsi dari setiap perintah yang
didukung oleh perangkat lunak.
8. Pesan kesalahan dan penyelesaian masalah : Deskripsi kesalahan yang dapat
dilaporkan dan cara memulihkan dari kesalahan ini.
9. Glosarium : Definisi istilah khusus yang digunakan.
10. Informasi terkait : sumber Referensi atau tautan ke dokumen lain yang
memberikan informasi tambahan
11. Fitur navigasi : Fitur yang memungkinkan pembaca menemukan saat ini lokasi
dan bergerak di sekitar dokumen.
12. Indeks : Daftar istilah kunci dan halaman di mana istilah-istilah ini
dirujuk.
13. Kemampuan pencarian : Dalam dokumentasi elektronik, cara menemukan istilah
tertentu dalam dokumen.
Penting untuk merancang ini dengan hati-hati saat membuat dokumentasi. Dengan
sistem perangkat lunak, Anda harus merancang struktur dokumen sehingga bagian yang
berbeda adalah sebagai independen mungkin. Ini memungkinkan setiap bagian untuk dibaca
sebagai satu item dan mengurangi masalah referensi silang ketika ada perubahan untuk dibuat.
Penataan dokumen dengan benar juga memungkinkan pembaca untuk menemukan informasi
lebih lanjut dengan mudah. Selain komponen dokumen seperti daftar isi dan indeks, dokumen
yang terstruktur dengan baik dapat dibaca sekilas sehingga pembaca dapat dengan cepat
menemukan bagian atau sub-bagian yang paling menarik bagi mereka.
Standar IEEE untuk dokumentasi pengguna (IEEE, 2001) mengusulkan bahwa: struktur
dokumen harus mencakup komponen yang ditunjukkan pada Gambar 2. standar memperjelas
bahwa ini adalah fitur yang diinginkan atau penting dari sebuah dokumen tetapi menjelaskan
bahwa cara komponen ini disediakan bergantung pada desainer dokumentasi. Beberapa (seperti
daftar isi) adalah sebagai berikut :
 Dukungan Kolaboratif untuk Desain Sistem
Judul: Tampilan Aktif
Proyek: MRC 842317
Pengidentifikasi dokumen: CSSD/CS/WD/17
Jenis dokumen: Kertas kerja teknis
Versi: 1.2 Tanggal: 20 Desember 2000
Pengarang: Ian Sommerville
Diperiksa: T/A. Disetujui: T/A
Dikirim ke CM:
Pengenal CM:
Distribusi: Daftar proyek
Kerahasiaan: Komersial
Kata kunci: Antarmuka pengguna, pembaruan tampilan, agen

© Universitas Lancaster 2000

Gambar 3: Contoh halaman sampul dokumen

Bagian yang terpisah dengan jelas; komponen lain seperti fitur navigasi akan ditemukan di
seluruh dokumen. Seperti yang saya bahas di bagian selanjutnya, standar IEEE ini adalah
standar umum dan, jika penggunaan standar ini diamanatkan, maka semua komponen ini harus
termasuk. Namun, banyak organisasi akan menggunakan standar sebagai panduan dan akan
tidak harus mencakup semua komponen yang ditunjukkan pada Gambar 2. Dengan demikian
keadaan, ada beberapa pedoman penataan minimal yang saya percaya harus selalu diikuti:
1. Semua dokumen, betapapun pendeknya, harus memiliki halaman sampul yang
mengidentifikasi proyek, dokumen, penulis, tanggal produksi, jenis dokumen, manajemen
konfigurasi dan informasi jaminan kualitas, penerima dokumen yang dituju, dan kelas
kerahasiaan dokumen. Ini juga harus mencakup informasi untuk pengambilan dokumen
 (abstrak atau kata kunci) dan pemberitahuan hak cipta. Gambar 3 adalah contoh
kemungkinan sampul depan format.
2. Dokumen yang panjangnya lebih dari beberapa halaman harus dibagi menjadi: bab dengan
setiap bab disusun menjadi bagian dan sub-bagian. A halaman konten harus dibuat dengan
mencantumkan bab, bagian, dan sub-bagian. Skema penomoran yang konsisten untuk bab,
bagian dan sub-bagian harus didefinisikan dan bab-bab harus halaman individual
bernomor (nomor halaman harus bab-halaman). Ini menyederhanakan perubahan
dokumen karena setiap bab dapat diganti tanpa mencetak ulang seluruh dokumen.
3. Jika sebuah dokumen berisi banyak detail, informasi referensi seharusnya memiliki indeks.
Indeks yang komprehensif memungkinkan informasi menjadi ditemukan dengan mudah
dan dapat membuat dokumen yang ditulis dengan buruk dapat digunakan. Tanpa indeks,
dokumen referensi hampir tidak berguna.
4. Jika sebuah dokumen ditujukan untuk spektrum pembaca yang luas yang mungkin
memiliki: kosakata yang berbeda, glosarium harus disediakan yang mendefinisikan istilah
teknis dan akronim yang digunakan dalam dokumen.
Struktur dokumen sering didefinisikan sebelumnya dan ditetapkan dalam dokumentasi
standar. Ini memiliki keuntungan dari konsistensi meskipun dapat menyebabkan masalah.
Standar mungkin tidak sesuai dalam semua kasus dan tidak wajar struktur mungkin harus
digunakan jika standar dipaksakan tanpa pertimbangan.

Standar Dokumentasi
Standar dokumentasi bertindak sebagai dasar untuk jaminan kualitas dokumen. Dokumen yang
dihasilkan menurut standar yang sesuai memiliki konsistensi penampilan, struktur dan kualitas.
Saya sudah memperkenalkan standar IEEE untuk dokumentasi pengguna di bagian sebelumnya
dan akan membahas standar ini di lebih detail sebentar lagi. Namun, bukan hanya standar yang
berfokus pada
dokumentasi yang relevan. Standar lain yang mungkin digunakan dalam proses dokumentasi
adalah:
1. Standar proses Standar ini menentukan proses yang harus diikuti untuk produksi dokumen
berkualitas tinggi.
2. Standar produk Ini adalah standar yang mengatur dokumen diri.
3. Pertukaran standar Semakin penting untuk bertukar salinan dokumen melalui surat
elektronik dan untuk menyimpan dokumen dalam database. Standar pertukaran memastikan
bahwa semua salinan dokumen elektronik kompatibel.
Standar, pada dasarnya, dirancang untuk mencakup semua kasus dan, akibatnya, dapat
terkadang tampak tidak perlu membatasi. Oleh karena itu penting bahwa, untuk setiap proyek,
standar yang sesuai dipilih dan dimodifikasi agar sesuai dengan itu proyek tertentu. Proyek
kecil mengembangkan sistem dengan waktu yang relatif singkat seumur hidup yang diharapkan
membutuhkan standar yang berbeda dari proyek perangkat lunak besar di mana perangkat
lunak mungkin harus dipertahankan selama 10 tahun atau lebih.
Standar proses
Standar proses menentukan pendekatan yang akan diambil dalam menghasilkan dokumen. Ini
umumnya berarti mendefinisikan perangkat lunak yang harus digunakan untuk produksi
dokumen dan mendefinisikan prosedur jaminan kualitas yang: memastikan bahwa dokumen
berkualitas tinggi dihasilkan.
Standar penjaminan mutu proses dokumen harus fleksibel dan harus mampu untuk menangani
semua jenis dokumen. Dalam beberapa kasus, di mana dokumen hanya kertas kerja atau memo,
tidak diperlukan pemeriksaan kualitas eksplisit. Namun, di mana dokumen adalah dokumen
formal, yaitu, ketika evolusi mereka akan terjadi dikendalikan oleh prosedur manajemen
konfigurasi, proses kualitas formal harus diadopsi. Gambar 3 mengilustrasikan satu proses
yang mungkin.
Merancang, memeriksa, merevisi, dan menyusun ulang adalah proses berulang yang harus
dilanjutkan sampai dokumen dengan kualitas yang dapat diterima dihasilkan. Yang dapat
diterima tingkat kualitas akan tergantung pada jenis dokumen dan pembaca potensial dari
dokumen.

Standar produk
Standar produk berlaku untuk semua dokumen yang dihasilkan selama pengembangan
perangkat lunak. Dokumen harus memiliki tampilan yang konsisten dan, dokumen dari kelas
yang sama harus memiliki struktur yang konsisten. Dokumen standar khusus untuk proyek
tetapi harus didasarkan pada yang lebih umum standar organisasi.
Contoh standar produk yang harus dikembangkan adalah:
1. Standar identifikasi dokumen Karena proyek besar biasanya menghasilkan ribuan dokumen,
setiap dokumen harus diidentifikasi secara unik. Untuk dokumen formal, pengenal ini mungkin
pengenal formal ditentukan oleh manajer konfigurasi. Untuk dokumen informal, gaya
pengidentifikasi dokumen harus ditentukan oleh proyek Pengelola.
2. Standar struktur dokumen Seperti yang telah dibahas pada bagian sebelumnya, ada struktur
yang sesuai untuk setiap kelas dokumen yang dihasilkan selama proyek perangkat lunak.
Standar struktur harus mendefinisikan ini organisasi. Mereka juga harus menentukan konvensi
yang digunakan untuk halaman penomoran, informasi header dan footer halaman, dan
penomoran bagian dan subbagian.
3. Standar presentasi dokumen Standar presentasi dokumen
mendefinisikan 'gaya rumah' untuk dokumen dan mereka berkontribusi secara signifikan untuk
mendokumentasikan konsistensi. Mereka termasuk definisi font dan gaya yang digunakan
dalam dokumen, penggunaan logo dan nama perusahaan, penggunaan warna untuk menyorot
struktur dokumen, dll.
4. Standar pembaruan dokumen Saat dokumen diubah untuk mencerminkan perubahan dalam
sistem, cara yang konsisten untuk menunjukkan perubahan ini seharusnya digunakan. Ini
mungkin termasuk penggunaan warna sampul yang berbeda untuk menunjukkan versi
dokumen baru dan penggunaan bilah perubahan untuk menunjukkan paragraf yang diubah atau
dihapus.
Standar dokumen harus berlaku untuk semua dokumen proyek dan dokumen awal draft
dokumentasi pengguna. Namun, dalam banyak kasus, dokumentasi pengguna memiliki untuk
disajikan dalam bentuk yang sesuai untuk pengguna daripada proyek dan itu harus dibentuk
kembali ke dalam bentuk itu selama proses produksi.

Standar pertukaran
Standar pertukaran dokumen penting karena semakin banyak dokumen diproduksi dalam
format elektronik serta atau bukan di atas kertas. Untuk dokumentasi yang dikirimkan dengan
sistem perangkat lunak, Adobe Portable Document Format (PDF) sekarang sangat umum
digunakan. Namun, ketika dokumen dipertukarkan oleh tim pengembangan dan draft diedarkan
dalam suatu organisasi ini sering dalam format kata apa pun prosesor yang digunakan
(seringkali Microsoft Word).
Dengan asumsi bahwa penggunaan pengolah kata standar dan pengeditan grafis sistem
diamanatkan dalam standar proses, standar pertukaran menentukan konvensi untuk
menggunakan alat-alat ini. Penggunaan standar pertukaran, memungkinkan dokumen untuk
ditransfer secara elektronik dan dibuat kembali dalam bentuk aslinya.
Standar pertukaran lebih dari sekadar kesepakatan untuk menggunakan versi sistem untuk
produksi dokumen. Contoh pertukaran standar mencakup penggunaan set makro standar yang
disepakati jika pemformatan teks sistem ini digunakan untuk produksi dokumen atau
penggunaan lembar gaya standar untuk pengolah kata. Standar pertukaran juga dapat
membatasi font dan gaya teks digunakan karena kemampuan printer dan tampilan yang
berbeda.

Standar IEEE untuk dokumentasi pengguna

Standar IEEE pertama untuk dokumentasi pengguna (IEEE, 1987) diproduksi di 1987
dan, pada saat penulisan, draf baru standar ini sedang disiapkan untuk publikasi (IEEE, 2001).
Seperti semua standar, standar ini merangkum kebijaksanaan dan pengalaman tentang
dokumentasi perangkat lunak dan mengusulkan struktur untuk dokumentasi pengguna.
Menggunakan struktur ini sebagai dasar, standar membahas konten pengguna perangkat lunak
dokumentasi dan mengusulkan standar format untuk dokumen-dokumen ini.
Saya sudah membahas struktur dokumentasi yang diusulkan oleh yang terbaru versi standar.
Untuk mengilustrasikan saran pemformatan dalam standar, berikut adalah beberapa kutipan
dari draf standar praktik yang baik saat ini:
Dokumentasi harus disediakan dalam media dan format yang memungkinkan: penggunaannya
oleh mereka yang memiliki penglihatan, pendengaran atau keterbatasan fisik lainnya.
Deskripsi tentang cara mencetak dokumentasi elektronik harus termasuk dalam dokumentasi
elektronik dan cetak.
Karena beberapa pengguna tidak dapat membedakan warna, dokumentasi harus memberikan
isyarat teks daripada menggunakan warna seperti merah dan hijau sebagai satu-satunya cara
untuk menyampaikan makna.
Peringatan, perhatian, dan catatan harus ditampilkan dalam format yang konsisten yang
mudah dibedakan dari teks biasa atau langkah-langkah instruksional
Format dokumentasi untuk perintah atau kode yang dimasukkan pengguna harus jelas:
membedakan antara literal (untuk menjadi input persis seperti yang ditunjukkan) dan variabel
(untuk dipilih oleh pengguna).
Ilustrasi yang menyertai teks akan muncul berdekatan dengan yang pertama referensi dalam
teks sehingga teks dan ilustrasi terkait dapat dilihat secara bersamaan.
Anda dapat melihat dari sini bahwa standar itu membantu tanpa menjadi larangan dan
oleh karena itu konvensi yang berbeda digunakan oleh perusahaan yang berbeda dan organisasi
dapat diakomodasi.
Seperti semua standar, standar dokumentasi ini harus disesuaikan dengan lokal situasi
di mana ia digunakan. Ini harus memberi contoh saran dalam standar untuk situasi lokal dan
menentukan struktur dan format khusus yang harus digunakan.
 Gaya menulis
Standar dan penilaian kualitas sangat penting jika ingin dokumentasi yang baik diproduksi
tetapi kualitas dokumen pada dasarnya tergantung pada penulis kemampuan untuk membangun
prosa teknis yang jelas dan ringkas. Singkatnya, bagus dokumentasi membutuhkan tulisan yang
baik.
Menulis dokumen dengan baik tidak mudah juga bukan proses satu tahap. Tertulis karya harus
ditulis, dibaca, dikritik dan kemudian ditulis ulang sampai memuaskan dokumen diproduksi.
Penulisan teknis adalah kerajinan daripada ilmu tetapi Beberapa pedoman umum tentang cara
menulis yang baik adalah:
1. Gunakan tenses aktif daripada pasif Lebih baik mengatakan 'Anda harus melihat kursor
berkedip di kiri atas layar' daripada 'A kursor berkedip akan muncul di kiri atas layar'.
2. Gunakan konstruksi tata bahasa yang benar dan ejaan yang benar Untuk dengan berani
teruslah memisahkan infinitif (seperti ini) dan salah mengeja kata (seperti salah mengeja)
mengganggu banyak pembaca dan mengurangi kredibilitas penulis dalam mata. Sayangnya,
ejaan bahasa Inggris tidak standar dan keduanya Pembaca Inggris dan Amerika terkadang tidak
rasional dalam ketidaksukaan mereka terhadap ejaan alternatif.
3. Jangan gunakan kalimat panjang yang menyajikan beberapa fakta berbeda lebih baik
menggunakan sejumlah kalimat yang lebih pendek. Setiap kalimat kemudian dapat menjadi
berasimilasi dengan sendirinya. Pembaca tidak perlu mempertahankan beberapa potongan
informasi pada satu waktu untuk memahami kalimat lengkap.
4. Buat paragraf tetap pendek Sebagai aturan umum, paragraf tidak boleh dibuat lebih dari
tujuh kalimat. Kapasitas kami untuk menahan segera informasi terbatas. Dalam paragraf
pendek, semua konsep dalam paragraf dapat dipertahankan dalam memori jangka pendek kita
yang dapat menampung sekitar 7 potongan informasi.
5. Jangan bertele-tele Jika Anda dapat mengatakan sesuatu dalam beberapa kata, lakukanlah.
A deskripsi yang panjang belum tentu lebih mendalam. Kualitas lebih penting kemudian
kuantitas.
6. Tepat dan tentukan istilah yang Anda gunakan Komputasi terminologi adalah cairan dan
banyak istilah memiliki lebih dari satu arti. Jika Anda menggunakan istilah seperti modul atau
proses, pastikan definisi Anda adalah jernih. Kumpulkan definisi dalam glosarium.
7. Jika deskripsinya rumit, ulangi diri Anda sendiri. Sering kali merupakan ide yang bagus
untuk
menyajikan dua atau lebih deskripsi frase yang berbeda dari hal yang sama. Jika pembaca gagal
untuk sepenuhnya memahami satu deskripsi, mereka mungkin manfaat dari memiliki hal yang
sama dikatakan dengan cara yang berbeda.
8. Manfaatkan heading dan sub-heading. Ini memecah sebuah bab menjadi bagian-bagian yang
dapat dibaca secara terpisah. Selalu pastikan bahwa konvensi penomoran yang konsisten
digunakan.
9. Perinci fakta sedapat mungkin. Biasanya lebih jelas untuk menyajikan fakta dalam daftar
bukan dalam kalimat. Gunakan penyorotan tekstual (miring atau menggarisbawahi) untuk
penekanan.
10. Jangan merujuk informasi hanya dengan nomor referensi. Berikan nomor referensi dan
mengingatkan pembaca tentang apa yang tercakup dalam referensi tersebut. Misalnya, daripada
mengatakan 'Di bagian 1.3 ...' Anda harus mengatakan 'Dalam bagian 1.3, yang menjelaskan
model proses manajemen, …’
Dokumen harus diperiksa dengan cara yang sama seperti program. Selama pemeriksaan
dokumen, teks dikritik, kelalaian ditunjukkan dan saran yang dibuat tentang cara memperbaiki
dokumen. Dalam hal terakhir ini, itu berbeda dari pemeriksaan kode yang merupakan
penemuan kesalahan daripada kesalahan mekanisme koreksi.
Selain kritik pribadi, Anda juga dapat menggunakan pemeriksa tata bahasa yang tergabung
dalam pengolah kata. Catur ini menemukan tata bahasa atau kikuk penggunaan kata-kata.
Mereka mengidentifikasi kalimat dan paragraf yang panjang dan penggunaan pasif daripada
tenses aktif. Catur ini tidak sempurna dan terkadang mereka menggunakan aturan gaya kuno
atau aturan yang khusus untuk satu hal negara. Namun demikian, karena mereka sering
memeriksa gaya saat Anda mengetik, mereka dapat membantu mengidentifikasi frasa yang
dapat ditingkatkan.

Dokumentasi online
Sekarang normal untuk memberikan beberapa dokumentasi online dengan pengiriman sistem
perangkat lunak. Ini dapat berkisar dari file 'baca saya' sederhana yang menyediakan sangat
informasi terbatas tentang perangkat lunak melalui interaktif berbasis hypertext membantu
sistem ke rangkaian lengkap dokumentasi sistem on-line. Paling umumnya, bagaimanapun,
sistem bantuan berbasis hypertext disediakan. Ini mungkin berdasarkan sistem hypertext
khusus atau mungkin berbasis HTML dan bergantung pada browser web untuk akses.
Keuntungan utama dengan dokumentasi on-line, tentu saja, aksesibilitasnya. Pengguna tidak
perlu menemukan manual, tidak ada kemungkinan untuk memilih dokumentasi up-of-date dan
fasilitas pencarian built-in dapat digunakan untuk mencari informasi dengan cepat.
Namun, sistem hypertext on-line memiliki beberapa kelemahan yang berarti: bahwa mereka
harus digunakan untuk melengkapi daripada menggantikan berbasis kertas dokumentasi. Ini
adalah:
• Mereka kurang 'browsability' sehingga pembaca tidak dapat dengan mudah membaca
sekilas mereka untuk menemukan informasi yang mereka butuhkan. Kita sering merasa
kesulitan untuk mencirikan informasi yang kita inginkan dari dokumentasi meskipun
kita dapat mengenalinya ketika kita menemukannya. Penjelajahan adalah mekanisme
utama yang kita gunakan saat mencari dengan cara ini. Penjelajahan juga menawarkan
peluang untuk penemuan fasilitas sistem yang tidak diketahui secara kebetulan.
• Layar, setidaknya dengan monitor yang biasa digunakan pada tahun 2001, memiliki
banyak resolusi lebih rendah dari kertas dan karenanya lebih sulit dan melelahkan untuk
membaca dokumen di layar daripada di atas kertas.
• Sangat mudah bagi pengguna untuk tersesat dalam sistem bantuan berbasis hypertext
dan akibatnya mereka merasa sulit untuk menavigasi ke mana mereka ingin pergi.

Saat merancang dokumentasi berbasis layar, Anda harus selalu menanggung ini masalah dalam
pikiran. Akibatnya, meskipun berbasis layar dan berbasis kertas dokumen harus ditulis dengan
baik, desain yang berbeda diperlukan untuk elektronik dan dokumentasi kertas. Karena
perbedaan antara layar dan kertas, cukup mengonversi dokumen pengolah kata ke HTML
(katakanlah) jarang menghasilkan dokumentasi on-line berkualitas tinggi.
Desain dokumen berbasis layar adalah topik utama dalam dirinya sendiri dan saya tidak punya
ruang untuk membahasnya di sini. Pembaca yang tertarik dapat menemukan ringkasan
pengantar topik ini di Bab 15 buku saya tentang rekayasa perangkat lunak (Sommerville, 2001)
dan catatan yang jauh lebih komprehensif dalam buku tentang Desain HCI oleh Dix et al
(1998).
 Persiapan Dokumen
Persiapan dokumen adalah proses membuat dokumen dan memformatnya untuk
publikasi. Gambar ke-3 menunjukkan proses persiapan dokumen yang dibagi menjadi 3 tahap
yaitu pembuatan dokumen, pemolesan dan produksi. Sistem pengolah kata modern sekarang
merupakan paket perangkat lunak terintegrasi yang mendukung semua bagian dari proses ini.
Namun, masih terjadi kasus untuk dokumen berkualitas tinggi, yang terbaik adalah
menggunakan alat terpisah untuk beberapa proses persiapan daripada fungsi pengolahan kata
bawaan. Tiga fase persiapan dan fasilitas pendukung terkait adalah:
1. Pembuatan dokumen. Input awal informasi dalam dokumen. Ini didukung oleh
pengolah kata dan pemformat teks, pemroses tabel dan persamaan, paket gambar
dan seni.
2. Pemolesan dokumen. Proses ini melibatkan perbaikan penulisan dan penyajian
dokumen agar lebih mudah dipahami dan dibaca. Ini melibatkan menemukan dan
menghapus ejaan, tanda baca dan kesalahan tata bahasa, mendeteksi frase yang
kaku dan menghapus redundansi dalam teks. Prosesnya mungkin didukung oleh
alat-alat seperti kamus online, pemeriksa ejaan, pemeriksa tata bahasa dan gaya,
dan pemeriksa gaya.
3. Produksi dokumen Ini adalah proses mempersiapkan dokumen untuk pencetakan
akhir. Ini didukung oleh paket penerbitan desktop, paket karya seni, dan program
penataan tipe.

Gambar 3 : Tahapan Penyusunan Dokumen

 Selain alat-alat ini untuk mendukung proses produksi dokumen, sistem manajemen
konfigurasi, sistem pengambilan informasi dan sistem hypertext juga dapat digunakan untuk
mendukung pemeliharaan, pengambilan, dan pengelolaan dokumen.
Sistem pengolah kata modern berbasis layar dan menggabungkan pengeditan dan
pemformatan teks. Gambar dokumen pada terminal pengguna, kurang lebih, sama dengan
bentuk akhir dari dokumen yang dicetak. Tata letak yang sudah selesai segera terlihat jelas.
Kesalahan dapat diperbaiki dan tata letak diperbaiki sebelum mencetak dokumen. Namun,
programmer yang sudah menggunakan editor untuk persiapan program terkadang lebih suka
menggunakan editor terpisah dan sistem pemformatan teks.
Sistem pemformatan teks seperti Lateks menafsirkan program tata letak yang
ditentukan oleh penulis dokumen. Perintah tata letak (sering dipilih dari kumpulan perintah
standar yang dapat ditentukan) diselingi dengan teks dokumen. Pemformat teks memproses
perintah-perintah ini dan teks terkait dan meletakkan dokumen sesuai dengan instruksi
pemrogram. Perbedaan antara sistem ini dan pengolah kata diilustrasikan pada Gambar 4.
Sistem pemformatan teks dapat melihat ke depan pada teks yang akan ditata sehingga dapat
membuat keputusan tata letak yang lebih baik daripada sistem pengolah kata yang konteks
kerjanya lebih terbatas. Karena perintahnya benar-benar bahasa pemrograman, programmer
sering kali lebih memilihnya daripada pengolah kata tetapi pengguna non-teknis lainnya
biasanya merasa lebih sulit untuk menggunakannya.

Gambar 4: Pengolah kata dan pemformat teks

Kerugian utama dari prosesor teks, setelah pemrograman mereka dikuasai, adalah
bahwa mereka tidak memberikan tampilan langsung dari output yang mereka hasilkan.
Pengguna harus memproses teks (ini mungkin memakan waktu beberapa menit) kemudian
menampilkan output menggunakan paket pratinjau. Jika kesalahan ditemukan, itu tidak dapat
segera diperbaiki. Sumber asli harus diubah dan proses pratinjau diulang. Jadi, meskipun dapat
menghasilkan dokumen dengan kualitas lebih tinggi, sebagian besar pengguna menganggap
pemformat teks lebih merepotkan daripada pengolah kata.
Tahap akhir produksi dokumen adalah tugas terampil yang, untuk dokumen dengan
cetakan besar, harus diserahkan kepada printer profesional. Namun, sistem desktop publishing
(DTP) dan sistem grafis yang mendukung pemindaian dan pemrosesan foto dan karya seni kini
tersedia secara luas. Ini telah merevolusi produksi dokumen. Sistem DTP mengotomatiskan
sebagian tata letak teks dan grafik. Mereka memungkinkan kontrol yang sangat halus atas tata
letak dan tampilan dokumen dan dapat digunakan oleh para insinyur untuk menghasilkan
dokumentasi sistem yang sudah jadi.
Keuntungan menggunakan sistem desktop publishing adalah biaya produksi dokumen
berkualitas tinggi berkurang karena beberapa langkah dalam proses produksi dihilangkan.
Bahkan dokumen yang diproduksi dalam jumlah kecil dapat diproduksi dengan standar yang
tinggi. Kerugian menggunakan sistem penerbitan desktop adalah bahwa mereka tidak
mengotomatiskan keterampilan desainer grafis. Kemudahan penggunaan yang menggoda
berarti bahwa mereka dapat diakses oleh pengguna yang tidak terampil yang dapat
menghasilkan dokumen yang tidak menarik dan dirancang dengan buruk.
Sejumlah besar dokumen dihasilkan selama proyek berlangsung dan ini perlu dikelola
sehingga versi dokumen yang tepat tersedia saat diperlukan. Jika sebuah proyek
didistribusikan, salinan dokumen akan diproduksi dan disimpan di lokasi yang berbeda dan
sangat penting untuk memelihara 'file induk' dokumen yang berisi versi definitif dari setiap
dokumen. Ini membantu meminimalkan masalah yang sangat umum yang muncul ketika
pengguna dokumen membuat kesalahan karena mereka tidak bekerja dari versi dokumen saat
ini

Gambar 5: Manajemen dokumen

 Setiap dokumen harus memiliki catatan unik dan ini dapat digunakan sebagai kunci
dalam catatan database dokumen. Namun, pengambilan oleh bidang lain seperti judul dan
penulis juga harus didukung.
Masalah mendasar dalam mengelola dokumen menggunakan sistem file untuk
menyimpan dokumen dan sistem manajemen basis data untuk memelihara informasi dokumen
adalah bahwa pengguna harus disiplin dalam menggunakan sistem mereka. Mereka harus
memastikan bahwa mereka memeriksa salinan dokumen dari sistem setiap kali mereka
membutuhkannya daripada menggunakan salinan lokal di komputer mereka atau salinan yang
telah mereka cetak. Dalam praktiknya, mencapai tingkat disiplin ini sulit dan kesalahan selalu
mungkin muncul.
Dalam proyek yang sangat besar, sistem manajemen dokumen khusus dapat digunakan
yang mengintegrasikan penyimpanan dokumen dan pemeliharaan informasi dokumen (Gambar
5). Perangkat lunak manajemen dokumen memungkinkan dokumen terkait untuk dihubungkan,
memelihara catatan siapa yang telah memeriksa dokumen, dapat mendukung kompresi dan
dekompresi teks dokumen dan menyediakan fasilitas pengindeksan dan pencarian informasi
sehingga dokumen dapat ditemukan. Sistem manajemen dokumen juga dapat mencakup
fasilitas manajemen versi sehingga versi dokumen yang berbeda dapat dipertahankan.