Dokumentasi perisian yang baik, sama ada dokumentasi spesifikasi untuk pengaturcara dan penguji, dokumen teknikal untuk pengguna dalaman, atau manual dan fail bantuan untuk pengguna akhir, akan membantu pengguna memahami ciri dan fungsi perisian. Dokumentasi yang baik adalah dokumentasi yang spesifik, jelas, dan relevan, dengan semua maklumat yang diperlukan oleh pengguna. Artikel ini akan membimbing anda untuk menulis dokumentasi perisian untuk pengguna teknikal dan pengguna akhir.
Langkah
Kaedah 1 dari 2: Menulis Dokumentasi Perisian untuk Pengguna Teknikal
Langkah 1. Ketahui maklumat apa yang perlu disertakan
Dokumen spesifikasi digunakan sebagai manual rujukan untuk pereka antara muka, pengaturcara yang menulis kod, dan penguji yang mengesahkan prestasi perisian. Maklumat yang perlu disertakan akan bergantung pada program yang dibuat, tetapi mungkin termasuk yang berikut:
- Fail penting dalam aplikasi, seperti file yang dibuat oleh pasukan pengembangan, pangkalan data yang diakses ketika program berjalan, dan aplikasi pihak ketiga.
- Fungsi dan subrutin, termasuk penjelasan mengenai penggunaan fungsi / subrutin, nilai input dan output.
- Pemboleh ubah dan pemalar program, dan bagaimana ia digunakan.
- Keseluruhan struktur program. Untuk program berasaskan pemacu, anda mungkin perlu menerangkan setiap modul dan perpustakaan. Atau, jika anda menulis manual untuk program berasaskan web, anda mungkin perlu menjelaskan fail mana yang digunakan setiap halaman.
Langkah 2. Tentukan tahap dokumentasi apa yang harus ada dan boleh dipisahkan dari kod program
Semakin banyak dokumentasi teknikal yang disertakan dalam kod program, semakin mudah memperbaharui dan menyelenggarakannya, serta menjelaskan berbagai versi program. Paling tidak, dokumentasi dalam kod program harus mencakup penggunaan fungsi, subrutin, pemboleh ubah, dan pemalar.
- Sekiranya kod sumber anda panjang, anda boleh menulis dokumentasi dalam fail bantuan, yang kemudian dapat diindeks atau dicari dengan kata kunci tertentu. Fail dokumentasi berasingan berguna jika logik program terbahagi kepada beberapa halaman dan termasuk fail sokongan, seperti aplikasi web.
- Beberapa bahasa pengaturcaraan (seperti Java, Visual Basic. NET, atau C #) mempunyai standard dokumentasi kod mereka sendiri. Dalam kes sedemikian, ikuti dokumentasi standard yang mesti disertakan dalam kod sumber.
Langkah 3. Pilih alat dokumentasi yang sesuai
Dalam beberapa kes, alat dokumentasi ditentukan oleh bahasa pengaturcaraan yang digunakan. Bahasa C ++, C #, Visual Basic, Java, PHP, dan lain-lain mempunyai alat dokumentasi mereka sendiri. Namun, jika tidak, alat yang digunakan akan bergantung pada dokumentasi yang diperlukan.
- Pemproses kata seperti Microsoft Word sesuai untuk membuat fail teks dokumen, asalkan dokumentasinya ringkas dan ringkas. Untuk membuat dokumentasi panjang dengan teks yang kompleks, kebanyakan penulis teknikal memilih alat dokumentasi khusus, seperti Adobe FrameMaker.
- Fail bantuan untuk mendokumentasikan kod sumber dapat dibuat dengan program penjana fail sokongan, seperti RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, atau HelpLogix.
Kaedah 2 dari 2: Menulis Dokumentasi Perisian untuk Pengguna Akhir
Langkah 1. Ketahui sebab perniagaan yang mendasari pembuatan manual
Walaupun alasan utama dokumentasi perisian adalah untuk membantu pengguna memahami cara menggunakan aplikasi, ada beberapa alasan lain yang mungkin mendasari pembuatan dokumentasi, seperti membantu bahagian pemasaran menjual aplikasi, meningkatkan imej syarikat, dan mengurangi sokongan teknikal kos. Dalam beberapa kes, dokumentasi diperlukan untuk mematuhi peraturan atau persyaratan hukum lainnya.
Walau bagaimanapun, dokumentasi bukanlah pengganti yang baik untuk antara muka. Sekiranya aplikasi memerlukan banyak dokumentasi untuk beroperasi, aplikasi harus dirancang agar lebih intuitif
Langkah 2. Ketahui sasaran pendokumentasian
Secara amnya, pengguna perisian mempunyai pengetahuan komputer yang terhad di luar aplikasi yang digunakan oleh mereka. Terdapat beberapa cara untuk memenuhi keperluan dokumentasi mereka:
- Perhatikan tajuk pengguna perisian. Sebagai contoh, pentadbir sistem umumnya memahami pelbagai aplikasi komputer, sementara setiausaha hanya mengetahui aplikasi yang dia gunakan untuk memasukkan data.
- Perhatikan pengguna perisian. Walaupun kedudukan mereka umumnya sesuai dengan tugas yang dilakukan, kedudukan ini mungkin mempunyai beban kerja yang berbeza, bergantung pada tempat perniagaan. Dengan menemubual bakal pengguna, anda dapat mengetahui apakah penilaian anda mengenai tajuk pekerjaan mereka betul.
- Perhatikan dokumentasi yang ada. Dokumentasi dan spesifikasi fungsi perisian dapat menunjukkan apa yang perlu diketahui oleh pengguna untuk menggunakannya. Walau bagaimanapun, ingat bahawa pengguna mungkin tidak berminat untuk mengetahui "jeroan" program.
- Ketahui apa yang diperlukan untuk menyelesaikan tugas, dan apa yang diperlukan sebelum anda dapat menyelesaikannya.
Langkah 3. Tentukan format yang sesuai untuk dokumentasi
Dokumentasi perisian boleh disusun dalam 1 atau 2 format, iaitu buku rujukan dan manual. Kadang kala, menggabungkan dua format adalah penyelesaian yang baik.
- Format rujukan digunakan untuk menjelaskan semua fitur perisian, seperti butang, tab, medan, dan kotak dialog, dan cara kerjanya. Beberapa fail bantuan ditulis dalam format ini, terutama yang sensitif konteks. Apabila pengguna mengklik Bantuan di layar tertentu, pengguna akan menerima topik yang relevan.
- Format manual digunakan untuk menjelaskan bagaimana melakukan sesuatu dengan perisian. Manual umumnya dalam format cetak atau PDF, walaupun beberapa halaman bantuan juga menyertakan arahan mengenai cara melakukan perkara tertentu. (Umumnya, format manual tidak peka konteks, tetapi mungkin dihubungkan dari topik sensitif konteks). Buku panduan umumnya dalam bentuk panduan, dengan ringkasan tugas-tugas yang akan dilakukan dalam penerangan dan panduan yang diformat dalam beberapa langkah.
Langkah 4. Tentukan jenis dokumentasi
Dokumentasi perisian untuk pengguna boleh dikemas dalam satu atau lebih format berikut: manual dicetak, fail PDF, fail bantuan, atau bantuan dalam talian. Setiap jenis dokumentasi dirancang untuk menunjukkan cara menggunakan fungsi perisian, sama ada panduan atau tutorial. Halaman dokumentasi dan bantuan dalam talian juga boleh merangkumi video demonstrasi, teks, dan gambar statik.
Fail bantuan dan sokongan dalam talian harus diindeks dan dicari menggunakan kata kunci supaya pengguna dapat dengan cepat mencari maklumat yang mereka perlukan. Walaupun aplikasi penjana fail bantuan dapat membuat indeks secara automatik, tetap disarankan agar anda membuat indeks secara manual menggunakan kata kunci yang biasanya dicari
Langkah 5. Pilih alat dokumentasi yang sesuai
Manual atau PDF yang dicetak dapat dibuat dengan program pemprosesan kata seperti Word atau penyunting teks lanjutan seperti FrameMaker, bergantung pada panjang dan kerumitan fail. Fail bantuan boleh ditulis dengan program pembuatan fail bantuan, seperti RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, atau HelpServer.
Petua
- Teks dokumentasi program harus disusun sedemikian rupa sehingga mudah dibaca. Letakkan gambar sedekat mungkin dengan teks yang sesuai. Pecah dokumentasi mengikut bahagian dan topik secara logik. Setiap bahagian atau topik harus menggambarkan masalah tertentu, baik ciri tugas dan program. Masalah berkaitan dapat dijelaskan dengan pautan atau senarai rujukan.
- Setiap alat dokumentasi yang dijelaskan dalam artikel ini dapat dilengkapi dengan program pembuat tangkapan layar, seperti SnagIt jika dokumentasi anda memerlukan banyak tangkapan layar. Seperti dokumentasi lain, anda juga harus menyertakan tangkapan skrin untuk membantu menjelaskan bagaimana aplikasi berfungsi, dan bukannya "memikat" pengguna.
- Memberi perhatian kepada gaya sangat penting, terutamanya jika anda menulis dokumentasi perisian untuk pengguna akhir. Alamat pengguna dengan kata ganti "anda", bukan "pengguna".
