Petunjuk Manual Dokumentasi

Pertemuan Minggu Pertama

Tim Pengajar:
Deddy Kusbianto
Elok Nur Hamdana
Pengantar
Apa yang Anda cari saat membeli produk tanpa buku
manual? Yaitu. ketika Anda nongkrong di bagian
komputer, bagaimana Anda memutuskan buku mana
yang akan dibeli?

Bagaimana Anda akan mengklasifikasikan buku

perangkat lunak (ke dalam jenis kategori apa)?
Dokumentasi
“Dokumentasi itu seperti makanan; ketika itu baik, itu
sangat, sangat baik, dan ketika itu buruk, itu lebih baik
daripada tidak sama sekali. " - Mengutip Dick Brandon

Jenis Dokumentasi
Penulisan teknis secara umum
Organisasi dokumentasi teknis
Instruksi menulis
Menulis manual pengguna
Referensi panduan organisasi
Jenis Dokumentasi Perangkat Lunak
Dokumentasi Internal
• Komentar dalam kode sumber
• Fasilitas bantuan dalam program
Dokumentasi eksternal
• Manual pengguna
• Pengaturan dan instruksi pemasangan
Kami menganggap Anda tahu bagaimana menulis
komentar dalam kode Anda
Di sini kita akan berkonsentrasi pada hal-hal lain
Penulisan Teknis
Teks tertulis yang membahas hal-hal seperti:
• Apa yang harus dilakukan seseorang untuk mencapai sesuatu
• Apa yang diketahui tentang topik tertentu
Orang-orang menggunakan tulisan teknis ketika:
• Mereka perlu mencari tahu tentang topik yang tidak mereka ketahui
• Mereka perlu mencari tahu lebih banyak tentang topik yang mereka tahu sedikit
tentangnya
Dua mode dasar menggunakan penulisan teknis:
• Menjelajah; pembaca membalik-balik atau membaca halaman-halamannya, berharap
mendapat gambaran keseluruhan konten
• Pencarian: pembaca mencari informasi tertentu
Penulisan teknis harus:
• Sajikan materi dengan cara yang mudah dicerna pembaca
• Materi yang terorganisir untuk membantu pembaca menemukan sesuatu dengan
mudah
Ingat, pembaca mungkin tidak tahu apa-apa tentang topik tersebut sebelum
membacanya.
Mengatur Dokumen Teknis
Tidak ada struktur pada dokumen, setiap halaman tampak seperti setiap
halaman lainnya
• Peramban tidak dapat melihat relevansi dari apa yang mereka baca dalam
konteks keseluruhan dokumen
• Pencari tidak dapat menemukan apa yang mereka cari dengan mudah.
Teknik untuk mengatur dokumen:
• Selesaikan penulisan nama bab, nama bagian, pos, subpos, judul paragraf
("unit" dokumen)
• Buat Daftar Isi
• Lengkapi dengan Indeks
Sebagian besar paket pengolah kata / teks dapat menghasilkan hal-hal ini
untuk kita secara otomatis
Namun, daftar isi, dll. Sangat berguna sehingga bila perlu harus dibuat dengan
tangan jika perlu.
Dilema Di Buku Pemrograman Java:
Yang mana yang Anda sajikan pertama dalam buku
Anda?

Konsep Objek
ATAU
Loop / Ifs / Variabel
Contoh Organisasi Dokumentasi Teknis
Java secara singkat, David Flanagan, O'Reilly, 1997
• Daftar Isi
• Kata pengantar
• Bagian I: Memperkenalkan Pemrograman Java
• Memberikan pengantar tutorial Java untuk orang yang lebih mengenal C
• Bagian II: Memperkenalkan Java 1.1
• Menjelaskan fitur-fitur di Java 1.1 bukan di 1.0
• Bagian III: Pemrograman dengan Java 1.1 API
• Berisi bab tentang applet, events, beans, serialization, dll.
• Bagian IV: Referensi Bahasa Jawa
• Sintaks, tag HTML, alat JDK
• Bagian V: Referensi Cepat API
• Bab pada masing-masing paket utama
• Indeks
Setiap Bagian berisi 2 hingga 16 bab
Instruksi Penulisan
•Instruksi tentang "bagaimana melakukan sesuatu" adalah umum dalam manual
pengguna
•Organisasi umum untuk serangkaian instruksi yang baik
•Paragraf pengantar yang menjelaskan tujuan instruksi
•Formulir daftar titik langkah individu sederhana
—Setiap langkah dimulai dengan beberapa kata perintah; misalnya "Klik"
"pilih"
—Poin bisa diberi nomor
•Catatan penjelasan harus dipisahkan dari instruksi itu sendiri; misalnya
•Tidak
Enter open <hostname> to be connected to <hostname>
•Meletakkannya seperti ini:
obelix[11]% open <hostname>
•Validasi instruksi Anda !!! (Note: this will connect you to <hostname>)
•Pergi melalui mereka di dunia nyata dan pastikan mereka benar-benar
berfungsi
Panduan pengguna

•User Manual: Teks yang dimaksudkan untuk membantu pengguna

beberapa produk (perangkat lunak, perangkat keras, dll)
—Pembaca = Pengguna, Pengguna = Pembaca
•Manual pengguna mungkin memiliki banyak tujuan:
—Beri tahu pengguna tentang cara menggunakan produk
—Jual produk ("menyenangkan dan mudah membuat gambar
menggunakan DrawingsRU Megasoft")
—Batasi tanggung jawab perusahaan atas produk
•Panduan pengguna yang datang dengan produk perangkat lunak
komersial bukan contoh terbaik
—Kadang-kadang tampaknya dimasukkan hanya karena pengguna
mengharapkannya
—Perusahaan mengandalkan penerbit buku seperti "DrawingRUs for
Morons" untuk menulis manual yang baik, tutorial.
Bahan dalam Manual Pengguna
Secara umum dua jenis materi muncul dalam buku petunjuk:
• Materi Tutorial
—Teks yang mengajarkan pengguna tentang konsep yang diperlukan
untuk menggunakan produk
—Instruksi memandu pengguna melalui detail tentang cara melakukan
tugas tertentu
• Materi referensi
—Perincian tujuan dan tujuan penggunaan setiap tombol, perintah,
panggilan
—Deklarasi fungsi individu dalam suatu API
Biasanya keduanya diperlukan
—Fasilitas produk biasanya dapat digunakan dalam berbagai cara yang
berbeda
—Tanpa materi tutorial, pengguna harus mengumpulkan keseluruhan
gambar
—Tanpa bahan referensi, pengguna akan kesulitan menemukan
informasi tentang topik tertentu
Fasilitas bantuan dalam program biasanya dari jenis "referensi"
Menulis Materi Tutorial
Bangun pengetahuan pembaca dari kurang menjadi lebih
• Jadikan bagian 1 sebagai materi yang tidak bergantung pada apa pun
• Buatlah bagian 2 yang hanya bergantung pada bagian 1
• Dll
Mulai dari spesifik ke umum atau umum ke spesifik
• Gunakan contoh diikuti oleh / didahului oleh diskusi yang lebih umum
• Diskusikan jenis tugas khusus (mis. Mengatur VCR untuk direkam
sekarang), kemudian tugas yang lebih umum (mis. Mengatur VCR untuk
direkam pada waktu tertentu) atau sebaliknya
Perkenalkan setiap bagian, paragraf, dll. Dengan sesuatu yang
• Memberitahu pembaca apa yang akan mereka pelajari di bagian ini
• Memberi pembaca informasi latar belakang apa saja yang perlu mereka
ketahui
Bahan Referensi Penulisan
•Biasanya, terdiri dari banyak bagian kecil
—Misalnya. satu untuk setiap tag, tombol, perintah, metode dll
—Dapat diatur dalam hierarki unit dokumen
•Sampaikan hal-hal serupa secara konsisten serupa
•Misalnya. deskripsi tag HTML:
—Tajuk dengan tag atau pasangan tag dan namanya
—Definisi singkat dari tag, menjelaskan tujuan, fungsi dan efek pada
dokumen
—Definisi dan penggunaan setiap atribut yang dapat digunakan untuk
memodifikasi fitur tag
—Daftar konteks (mis. Pasangan tag lainnya) tempat tag dapat muncul
secara legal
—Beberapa tip gaya / penggunaan
—Contoh penggunaan tag, dengan beberapa atribut diikuti oleh
tangkapan layar
•Setiap tag akan dijelaskan dengan cara ini
Definisi dalam Manual Referensi
•Definisi dapat diberikan dalam hierarki yang sesuai, mis.
—“<table> ... </table> Table: Membuat tabel. Tabel ini kosong kecuali
jika anda membuat baris dan sel menggunakan elemen <tr>, <td>. "
—Deskripsi tag elemen tabel diberikan segera setelah deskripsi tag
tabel
•Pembaca penulisan teknis yang berpengetahuan luas tidak perlu setiap
istilah didefinisikan
•Namun, definisi harus tetap:
•Gunakan kata-kata yang sudah dipahami pembaca, misalnya istilah umum
yang sudah diketahui pembaca dari pengalaman masa lalu atau yang telah
didefinisikan sebelumnya dalam teks, mis.
—Definisi tag tabel di atas hanya baik jika pembaca sudah tahu apa
yang dilakukan 3 tag lainnya
—Daftar tag yang ditutup dengan definisi singkat masing-masing
diberikan pada awal setiap bab
—Namun, tabel istilah, baris, dan sel tidak didefinisikan karena sudah
tidak asing lagi bagi siapa saja yang pernah menggunakan pengolah
kata
Contoh lain dari Halaman Web:
Dan akhirnya…
Perhatikan cara berpikir pembaca

Bacalah kembali apa yang telah anda tulis untuk

memeriksanya

Lihatlah dokumen-dokumen yang menurut anda sangat

membantu dan tirulah mereka
Tugas

Carilah Ide aplikasi atau sistem yang akan

kalian jadikan bahan dalam proses
pembuatan dokumentasi serta jabarkan
secara singkat kebutuhan dari aplikasi atau
sistem tersebut
Terimakasih

Tim Pengajar:
Deddy Kusbianto
Elok Nur Hamdana