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. Merupakan suatu hal yang penting untuk membedakan antara end-user dengan system administrator. 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. 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. The system installation document - Diperuntukan bagi system administrator. 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. Dokumen yang menggambarkan arsitektur dari sistem 3. Untuk setiap program yang ada pada sistem, gambaran arsitektur dari program tersebut. 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. Dokumen validasi. Menjelaskan bagaimana setiap program divalidasi dan kaitannya dengan spesifikasi kebutuhan yang diinginkan oleh pelanggan. Panduan sistem maintenance, yang menjelaskan permasalahan-permasalahan yang telah diketahui dapat terjadi pada sistem.
Gambar 2. 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.
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. Daftar Ilustrasi : berisi nomor ilustrasi dan nomor halamannya d. 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.
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. 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. 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. Apabila dokumen memiliki banyak penjelasan detil, informasi referensi harus diberi index. 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. 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. Standar produk. Standar yang mengatur dokumen itu sendiri. Merupakan hal yang penting untuk dapat bertukar dokumen melalui email dan menyimpannya dalam suatu database.
Standar pertukaran menjaga agar setiap dokumen dapat kompatibel. 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.
Standar Produk Produk standar berlaku untuk semua dokumen yang diproduksi oleh pengembang software. 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. Termasuk didalam struktur dokumen adalah penggunaan format penomoran halaman, header dan footer, penomoran bab dan sub-bab dll. Document presentation standards Mengatur style tampilan dari dokumen, termasuk di dalamnya jenis huruf yang digunakan, cover, pewarnaan, penggunaan logo dan nama perusahaan dll.
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. 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. Tidak mereferensikan informasi hanya dengan nomer referensi saja III.
Buatlah halaman sampul dan judul yang sesuai. Anda membutuhkan sampul depan untuk panduan pengguna apa pun yang lebih dari sekadar kartu referensi dan halaman judul untuk panduan yang mencakup lebih dari sekadar selembar kertas terlipat dengan panjang 4 halaman atau lebih. Jika panduan dilindungi oleh hak cipta, pemberitahuan hak cipta harus dicantumkan pada sampul depan dan belakang, serta pada halaman judul. Jika ada syarat dan ketentuan untuk menggunakan panduan dan produk yang terkait dengannya, cantumkan di bagian dalam sampul depan.
Letakkan referensi ke dokumen terkait dalam kata pengantar. Jika panduan pengguna lebih dari satu, buatlah referensi ke dokumen yang lain, dengan mencantumkan nomor versi yang benar, di sini. Dalam kebanyakan kasus, baik prosedur dan bahan referensi masing-masing harus memiliki bagian tersendiri.
Namun, Anda dapat memberi tahu pengguna untuk merujuk pada konten spesifik dalam satu bagian dan membedakannya dengan bagian lainnya. Dengan cara ini, pengguna bisa dengan cepat menemukan informasi yang dia cari.
Prosedur harus ditulis dalam struktur yang konsisten di seluruh bagian instruksi pada panduan. Mulailah dengan gambaran umum fungsi produk, lalu jelaskan apa yang harus dilakukan pengguna dan hasil apa yang akan dia dapatkan atau lihat. Langkah-langkahnya harus diberi nomor dan dimulai dengan kata kerja tindakan, seperti cara penulisan langkah-langkah dalam setiap bagian artikel ini.
Bahan referensi dapat meliputi daftar pilihan, kiat-kiat pemecahan masalah, dan pertanyaan umum. Glosarium dan indeks dapat ditambahkan di akhir panduan, meskipun daftar istilah yang sering digunakan bisa diberikan di awal. Indeks bisa diabaikan jika panduan memiliki kurang dari 20 halaman.
Gunakan gambar grafis sesuai kebutuhan untuk mendukung teks. Gambar grafis, atau tangkapan layar, dapat memberikan ilustrasi poin-poin tertentu dalam panduan secara lebih baik dibanding teks, terutama dalam prosedur kompleks yang membuat pengguna membutuhkan konfirmasi visual untuk memastikan mereka mengikuti langkah-langkah dengan benar. Gambar grafis dapat dibuat menggunakan computer-aided drafting CAD atau aplikasi pengedit grafis, kamera digital dan aplikasi pengolah foto, atau jika Anda ingin menggunakan tangkapan layar, gunakan fitur tangkapan layar yang ada di komputer atau program grafis dengan kemampuan menangkap layar.
Begitu Anda membuat gambar grafis, simpan dalam format terkompresi sehingga Anda dapat menggunakannya dalam aplikasi pengolah kata atau desktop publishing. Anda juga perlu memperkecil ukuran gambar agar lebih sesuai dengan halaman, tetapi tetap memberikan detail yang lengkap untuk pengguna.
Jika perlu, Anda bisa memotong gambar asli menjadi beberapa bagian dan menunjukkan bagian yang relevan bersama teks yang mendukungnya. Jika Anda menggunakan banyak gambar grafis dalam prosedur, pastikan gambar dibuat dengan ukuran yang konsisten, entah dalam dimensi panjang dan lebar yang sama atau dalam proporsi memperkecil ukuran gambar asli. Dengan begitu, gambar akan terlihat lebih menarik bagi pengguna.
Hal yang sama juga berlaku saat membuat tangkapan layar dari komputer; pastikan komputer menampilkan skema warna standar saat mengambil gambar jika panduan akan menampilkan tangkapan layar berwarna. Meskipun aplikasi pengedit gambar seperti Photoshop dan Paint Shop Pro memiliki kemampuan pengambilan gambar yang baik, program yang didedikasikan untuk mengambil tangkapan layar seperti SnagIt juga menawarkan kemampuan untuk memodifikasi, membuat katalog dan anotasi pada tangkapan layar dengan mudah.
Bagian 3. Pilih beberapa fon yang mudah dibaca. Meskipun komputer dapat mendukung sejumlah fon, tujuan pembuatan panduan pengguna adalah mudah dibaca. Memilih beberapa fon yang serasi adalah cara terbaik untuk mencapai tujuan tersebut. Fon bisa dikelompokkan menjadi dua jenis: serif dan sans serif.
Fon serif memiliki garis hias kecil di ujung garis utama yang membentuk huruf. Fon serif sangat cocok untuk sebagian besar teks yang ditampilkan dalam ukuran di batang tubuh utama untuk panduan cetak. Fon sans serif hanya menampilkan garis yang membentuk huruf, tanpa hiasan. Fon yang termasuk kelompok sans serif di antaranya Arial , Calibri , dan Century Gothic. Fon sans serif dapat digunakan untuk sebagian besar teks dengan ukuran 8 sampai 10 dalam file PDF atau panduan daring, meskipun dengan tidak adanya hiasan membuat kalimat yang ditampilkan dengan fon ukuran 12 atau lebih besar menjadi lebih sulit dibaca.
Namun, fon dapat digunakan secara efektif dalam ukuran lebih besar untuk menampilkan judul dan heading , dan dalam ukuran lebih kecil sangat cocok untuk catatan kaki dan nomor dalam kolom dan tabel.
Secara umum, akan lebih baik jika Anda memilih fon sederhana seperti Arial atau Times New Roman untuk panduan, meskipun Anda dapat menggunakan fon dekoratif untuk kutipan atau judul jika Anda menulis panduan untuk gim video dengan latar fantasi atau fiksi ilmiah. Dalam hal kutipan, sering kali Anda dapat menggunakan fon sederhana dan menampilkan kutipan lengkap dengan huruf miring.
Setelah memutuskan fon-fon yang akan digunakan, buatlah halaman contoh untuk memverifikasi bahwa fon-fon tersebut terlihat serasi di atas kertas. Anda juga harus menunjukkan halaman contoh ini kepada orang yang bertanggung jawab memberikan persetujuan untuk tampilan panduan sebelum Anda melanjutkan dengan proses penulisan.
Pikirkan tentang tata letak. Setelah memilih fon untuk panduan, Anda harus memutuskan bagaimana menyusun konten di atas halaman. Secara umum, Anda mungkin harus menempatkan judul dokumen atau judul bab dalam header atau footer , mungkin menggunakan judul panduan di sebelah kiri halaman dan judul bab di sebelah kanan halaman. Anda harus menempatkan nomor halaman di header atau footer , entah di luar header atau footer atau di tengah hanya di footer.
Anda mungkin juga perlu membedakan halaman pertama setiap bagian atau bab dari halaman lain dengan menempatkan nomor halaman di tengah footer dan halaman berikutnya di sudut luar header. Anda mungkin perlu membuat teks sisipan di dalam kotak berwarna atau kotak yang diblok untuk membedakannya dengan teks lainnya. Pastikan Anda memilih warna atau tingkat pengeblokan sehingga tidak membuat teks sulit dibaca.
Berikan margin yang cukup lebar di semua sisi, dengan ruang ekstra di bagian tepi yang akan dijilid. Pertimbangkan jenis jilid untuk panduan pengguna. Jika panduan lebih dari 4 halaman, halaman harus dijilid dengan cara tertentu. Meskipun dokumen internal dapat dijepit dengan stapler di sudut halaman, panduan pengguna eksternal yang dikirimkan bersama produk biasanya dijilid dengan salah satu dari 3 metode berikut: Metode side-stapling dijepit pada bagian sisi halaman dengan stapler untuk panduan yang dicetak di kertas berukuran 21 x 27,5 cm, 21 x 35 cm, atau 27,5 x 42,5 cm yang dilipat.
Sebagian besar panduan murah yang terdiri dari 48 halaman atau lebih sedikit dijilid dengan cara seperti ini. Metode saddle-stitching dijahit di bagian sisi halaman lebih sering digunakan untuk panduan referensi pihak ketiga dibanding panduan yang disertakan dengan produk selain mobil, meskipun beberapa panduan yang lebih panjang dijilid dengan cara ini. Jilid spiral paling cocok untuk panduan yang digunakan di lingkungan yang lebih keras, misalnya di luar ruangan dalam hal ini metode side-stapling dan saddle-stitching tidak cukup kuat sehingga halaman akan terlepas.
Beberapa panduan yang dijilid spiral mungkin juga dilengkapi halaman yang dilaminasi plastik untuk mencegah agar tidak rusak saat basah atau terkena lumpur. Buatlah dokumen templat untuk panduan. Banyak aplikasi pengolah kata dan desktop publishing menawarkan pilihan untuk membuat dokumen templat untuk panduan pengguna.
Jadi, saat Anda mengetik, teks akan muncul secara otomatis dengan fon yang Anda pilih untuk bagian panduan yang sedang Anda kerjakan. Sebenarnya, artikel ini pada awalnya ditulis menggunakan templat Microsoft Word.
Sebagian besar program ini juga menyertakan seperangkat templat standar yang dapat Anda modifikasi sesuai kebutuhan sehingga Anda tidak perlu membuat templat sendiri dari nol. Anda dapat memilih salah satu nama gaya yang telah ditetapkan misalnya, Heading , Normal, Quote atau membuat gaya sendiri dengan nama sendiri. Sedapat mungkin, ikuti konvensi untuk membuat nama gaya jika Anda memiliki beberapa gaya untuk jenis teks yang sama.
0コメント