Dokumentasi perangkat lunak yang baik, baik berupa dokumentasi spesifikasi bagi pemrogram dan penguji, dokumen teknis untuk pengguna internal, atau manual dan berkas pertolongan untuk pengguna akhir, akan membantu pengguna memahami fitur dan fungsi perangkat lunak. Dokumentasi yang baik adalah dokumentasi yang spesifik, jelas, dan relevan, dengan seluruh informasi yang diperlukan pengguna. Artikel ini akan memandu Anda untuk menulis dokumentasi perangkat lunak bagi pengguna teknis dan pengguna akhir.
Langkah
-
Ketahui informasi apa saja yang perlu disertakan. Dokumen spesifikasi digunakan sebagai manual referensi bagi perancang antarmuka, pemrogram yang menulis kode, dan penguji yang memverifikasi kinerja perangkat lunak. Informasi yang perlu disertakan akan bergantung pada program yang tengah dibuat, tetapi mungkin menyertakan beberapa hal berikut:
- Berkas penting dalam aplikasi, seperti berkas yang dibuat tim pengembang, basis data yang diakses saat program beroperasi, dan aplikasi pihak ketiga.
- Fungsi dan subrutin, termasuk penjelasan kegunaan fungsi/subrutin, nilai masukan, dan keluaran.
- Variabel dan konstanta program, dan bagaimana seluruh variabel/konstanta tersebut digunakan.
- Struktur program secara keseluruhan. Untuk program berbasis kandar, Anda mungkin perlu menjelaskan masing-masing modul serta pustaka. Atau, jika Anda menulis manual untuk program berbasis web, Anda mungkin perlu menjelaskan berkas mana yang digunakan oleh setiap halaman.
-
Putuskan tingkat dokumentasi yang harus ada dan dapat dipisahkan dari kode program. Semakin banyak dokumentasi teknis yang tercantum dalam kode program, akan semakin mudah pula dokumentasi tersebut diperbarui dan dirawat, juga digunakan untuk menjelaskan berbagai versi program yang berbeda. Secara minimal, dokumentasi pada kode program harus menyertakan kegunaan fungsi, subrutin, variabel, dan konstanta.
- Jika kode sumber Anda panjang, Anda dapat menulis dokumentasi dalam berkas pertolongan, yang kemudian dapat diindeks atau dicari dengan kata kunci tertentu. Berkas dokumentasi terpisah akan berguna jika logika program terpecah dalam beberapa halaman dan menyertakan berkas dukungan, seperti aplikasi web.
- Beberapa bahasa pemrograman (seperti Java, Visual Basic.NET, atau C#) memiliki standar dokumentasi kode tersendiri. Dalam kasus tersebut, ikuti standar dokumentasi yang harus disertakan dalam kode sumber.
-
Pilih alat dokumentasi yang sesuai. Dalam beberapa kasus, alat dokumentasi ditentukan dari bahasa program yang digunakan. Bahasa C++, C#, Visual Basic, Java, PHP, dan lain-lain memiliki alat dokumentasi tersendiri. Namun, jika tidak, alat yang digunakan akan bergantung pada dokumentasi yang diperlukan.
- Pengolah kata seperti Microsoft Word cocok digunakan untuk membuat berkas teks dokumentasi, selama dokumentasi tersebut ringkas dan sederhana. Untuk membuat dokumentasi panjang dengan teks yang kompleks, kebanyakan penulis teknis memilih alat dokumetasi khusus, seperti Adobe FrameMaker.
- Berkas pertolongan untuk mendokumentasikan kode sumber dapat dibuat dengan program pembuat berkas dukungan, seperti RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, atau HelpLogix.
Iklan
-
Ketahui alasan bisnis yang mendasari pembuatan manual. Meskipun alasan utama dokumentasi perangkat lunak adalah untuk membantu pengguna memahami cara penggunaan aplikasi, ada beberapa alasan lain yang mungkin mendasari pembuatan dokumentasi, seperti membantu bagian pemasaran menjual aplikasi, meningkatkan citra perusahaan, dan mengurangi biaya dukungan teknis. Dalam beberapa kasus, dokumentasi diperlukan untuk memenuhi regulasi atau aturan hukum lainnya.
- Namun, dokumentasi bukanlah pengganti antarmuka yang baik. Jika suatu aplikasi memerlukan banyak dokumentasi untuk dapat dioperasikan, sebaiknya aplikasi tersebut dirancang agar lebih intuitif.
-
Ketahui sasaran pembaca dokumentasi. Umumnya, pengguna perangkat lunak memiliki pengetahuan komputer yang terbatas di luar aplikasi yang digunakan oleh mereka. Ada beberapa cara untuk memenuhi kebutuhan dokumentasi mereka:
- Perhatikan jabatan pengguna perangkat lunak. Misalnya, administrator sistem umumnya memahami berbagai aplikasi komputer, sementara sekretaris hanya menguasai aplikasi yang ia gunakan untuk memasukkan data.
- Perhatikan pengguna perangkat lunak. Meskipun jabatan mereka umumnya sesuai dengan tugas yang dijalankan, jabatan tersebut mungkin memiliki beban kerja yang berbeda, tergantung tempat usaha. Dengan mewawancarai calon pengguna, Anda dapat mengetahui apakah penilaian Anda akan jabatan mereka sudah tepat.
- Perhatikan dokumentasi yang sudah ada. Dokumentasi dan spesifikasi fungsi perangkat lunak dapat menunjukkan apa saja yang harus diketahui pengguna agar dapat menggunakannya. Namun, ingatlah bahwa pengguna mungkin tidak tertarik mengetahui "jeroan" program.
- Ketahui hal-hal yang diperlukan untuk menyelesaikan tugas, dan hal apa saja yang diperlukan sebelum dapat menyelesaikannya.
-
Tentukan format yang sesuai untuk dokumentasi. Dokumentasi perangkat lunak dapat disusun dalam 1 atau 2 format, yaitu buku referensi dan buku panduan. Terkadang, menggabungkan kedua format adalah solusi yang baik.
- Format referensi digunakan untuk menjelaskan seluruh fitur perangkat lunak, seperti tombol, tab, kolom isian, dan kotak dialog, dan cara kerjanya. Sebagian berkas pertolongan ditulis dengan format ini, terutama berkas yang sensitif terhadap konteks. Saat pengguna mengeklik Help di layar tertentu, pengguna akan menerima topik yang relevan.
- Format buku panduan digunakan untuk menjelaskan cara melakukan suatu hal dengan perangkat lunak. Buku panduan umumnya dibuat dalam format cetak atau PDF, meskipun beberapa halaman pertolongan juga menyertakan panduan melakukan hal tertentu. (Umumnya, format buku panduan tidak sensitif terhadap konteks, tetapi mungkin ditautkan dari topik yang sensitif terhadap konteks). Buku panduan umumnya berbentuk panduan, dengan ringkasan tugas yang akan dilakukan dalam deskripsi dan panduan yang diformat dalam bentuk langkah.
-
Putuskan jenis dokumentasi. Dokumentasi perangkat lunak untuk pengguna mungkin dikemas dalam salah satu atau beberapa format berikut: buku manual cetak, berkas PDF, berkas pertolongan, atau pertolongan daring. Setiap jenis dokumentasi dirancang untuk menunjukkan cara menggunakan fungsi perangkat lunak, baik berupa panduan maupun tutorial. Dokumentasi daring dan halaman pertolongan juga mungkin menyertakan video demonstrasi, teks, dan gambar statis.
- Berkas pertolongan dan dukungan daring harus terindeks dan dapat dicari menggunakan kata kunci agar pengguna dapat menemukan informasi yang diperlukan dengan cepat. Meskipun aplikasi pembuat berkas pertolongan dapat membuat indeks secara otomatis, Anda tetap dianjurkan untuk membuat indeks secara manual dengan kata kunci yang umum dicari.
-
Pilih alat dokumentasi yang sesuai. Buku manual cetak atau PDF dapat dibuat dengan program pengolah kata seperti Word atau penyunting teks canggih seperti FrameMaker, tergantung panjang dan kompleksitas berkas. Berkas pertolongan dapat ditulis dengan program pembuat berkas pertolongan, seperti RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, atau HelpServer.Iklan
Tips
- Teks pada dokumentasi program sebaiknya disusun sedemikian rupa agar mudah dibaca. Letakkan gambar sedekat mungkin dengan teks yang sesuai. Pecah dokumentasi berdasarkan bagian dan topik secara logis. Setiap bagian atau topik harus menjelaskan masalah tertentu, baik tugas maupun fitur program. Masalah terkait dapat dijelaskan dengan tautan atau daftar referensi.
- Setiap alat dokumentasi yang dijelaskan di artikel ini dapat dilengkapi dengan program pembuat tangkapan layar, seperti SnagIt jika dokumentasi Anda memerlukan banyak tangkapan layar. Layaknya dokumentasi lain, Anda juga harus menyertakan tangkapan layar untuk membantu menjelaskan cara kerja aplikasi, alih-alih "memikat" pengguna.
- Memperhatikan gaya bahasa sangatlah penting, terutama jika Anda menulis dokumentasi perangkat lunak bagi pengguna akhir. Sebut pengguna dengan kata ganti "Anda", alih-alih "pengguna".
Iklan
Hal yang Anda Butuhkan
- Program pembuat dokumentasi
- Program pembuat tangkapan layar
Referensi
- http://www.softwaredocumentation.info/DocumentingSoftware.aspx
- http://www.techscribe.co.uk/ta/how-to-write-user-documentation.htm
- http://www.techscribe.co.uk/ta/how-to-write-instructions.htm
- Rodney Ruff, Omaha, NE; berpengalaman menjadi penulis teknis dan pembuat berkas dokumentasi sejak 1997.
Tentang wikiHow ini
Halaman ini telah diakses sebanyak 45.222 kali.
Iklan