Kiat untuk menulis dokumentasi teknis yang kompeten untuk pengguna.
Bagian 1
Dalam salah satu artikel sebelumnya, kami menguraikan bagaimana proses
mendokumentasikan dan melokalkan produk kami terjadi.
Kali ini, di bawah potongan, adalah manual dari
penulis teknis kami Andrei Starovoitov, yang akan membantu membuat dokumentasi Anda lebih mudah dan lebih mudah dipahami oleh pengguna (teknik yang dijelaskan digunakan oleh Apple, Microsoft dan perusahaan lain untuk mendokumentasikan produk mereka).
Seperti yang Anda ketahui, dokumentasi yang baik bukanlah barang mewah, tetapi sarana untuk meningkatkan penjualan perusahaan. Jika Anda akan memulai atau sudah mengembangkan beberapa jenis program, maka untuk memasuki pasar dunia dengan itu, Anda akan memerlukan buku petunjuk (alias Panduan Pengguna) atau setidaknya dokumen yang memberi tahu pelanggan cara mulai bekerja dengan produk Anda (yang disebut Memulai dengan).
Dalam bahasa apa untuk menulis dokumentasi - dalam bahasa Rusia, dan kemudian menerjemahkannya, atau segera dalam bahasa Inggris - Anda yang memutuskan. Di Parallels, kami memilih pendekatan kedua. Sering kali lebih mudah untuk membuat deskripsi dalam bahasa Inggris, karena hampir semua (dan sekarang kita dapat mengatakan bahwa "semua") istilah komputer dalam bahasa Rusia dipinjam.
Lebih jauh dalam teks, kami akan fokus pada contoh Rusia dan Inggris.
Jadi apa yang harus Anda cari saat menulis dokumentasi?
Jenis topik dalam dokumentasi
Saat menulis topik, pertama-tama Anda perlu menentukan topik apa yang akan dibahas :)
Dari sini akan tergantung pada apa dan bagaimana menulis di dalamnya.
Ada
4 jenis topik utama :
•
Topik yang menjelaskan bagaimana menyelesaikan tugas tertentu atau beberapa tugas terkait (dalam bahasa Inggris jenis topik ini disebut
halaman tugas) .
Misalnya, "Instal Parallels Desktop" atau "Shut Down atau Pause Windows." Setiap topik ini menjelaskan serangkaian satu atau beberapa langkah yang harus dilakukan pengguna untuk mencapai tujuan tertentu. Manual pengguna terutama terdiri dari topik-topik seperti itu.
Biasanya pengguna tidak suka membaca, terutama ketika ada banyak teks. Karena itu, Anda harus mencoba membuat topik semacam itu sesingkat mungkin. Idealnya, jika informasi disajikan dalam bentuk berikut: "Anda dapat melakukan sesuatu, cukup klik di sini dan di sini" (topik tugas akan dibahas secara lebih rinci di bagian artikel selanjutnya).
Jika pengembang percaya bahwa ada informasi tambahan yang perlu diketahui pengguna, dan ada banyak informasi, maka ini paling baik dijelaskan dalam topik konseptual (lihat di bawah).
•
Topik konseptual (dalam bahasa Inggris -
halaman konsep ). Dalam topik ini tidak ada instruksi tentang bagaimana menyelesaikan masalah apa pun. Mereka berisi informasi yang lebih berkontribusi pada pemahaman yang lebih besar tentang berbagai hal. Misalnya, topik konseptual digunakan untuk:
- Jelaskan kepada pengguna bagaimana proses bekerja;
- katakan apa yang bisa dilakukan dalam pengaturan aplikasi;
- menjelaskan fitur yang ditambahkan dalam versi baru produk;
- memberikan informasi tambahan yang akan membantu pengguna lebih memahami atau memecahkan masalah.
Harap dicatat bahwa informasi tambahan (jika ada banyak) harus diberikan secara tepat dalam topik konseptual agar tidak membebani topik tugas.
•
Topik bantuan (dalam bahasa Inggris -
halaman referensi ) - berisi informasi yang dapat dirujuk pengguna secara berkala untuk mengetahui apa arti istilah tertentu, cara kerja suatu fungsi, dll. Contoh bagus dari topik tersebut adalah kamus di akhir panduan (alias Daftar Istilah). Topik referensi sangat berguna untuk menjelaskan tujuan dari berbagai elemen antarmuka.
•
Topik yang menjelaskan cara mengatasi masalah (dalam bahasa Inggris -
halaman pemecahan masalah ).
Misalnya: "Saya tidak bisa mengaktifkan Parallels Desktop" atau "Saya tidak bisa terhubung ke Internet." Topik-topik ini menjelaskan apa yang perlu dilakukan untuk menyelesaikan masalah. Mereka juga dapat berisi informasi yang akan membantu untuk memahami apa penyebab dari kerusakan tersebut.
Instruksi dasar untuk semua jenis dokumentasi
Saat membuat panduan:
1)
Berkonsentrasi pada pengguna
• Alih-alih menyusun deskripsi produk berdasarkan fitur atau elemen antarmuka, cobalah berkonsentrasi pada tugas yang paling mungkin dipecahkan pengguna.
Misalnya, topik tentang cara melindungi data di mesin virtual dapat disebut 2 cara:
a) "Pengaturan Keamanan", yang menjelaskan secara terperinci apa yang dapat dilakukan untuk melindungi data.
b) Buat beberapa topik yang menjelaskan tugas tertentu:
- “Lindungi Data Anda dengan Perangkat Lunak Antivirus”
- “Cadangkan mesin virtual Anda” (“Cadangkan Mesin Virtual Anda”)
Menurut tren saat ini dalam dokumentasi, pendekatan kedua lebih disukai, karena dalam hal ini pengguna tidak perlu menebak apakah akan melakukan sesuatu atau tidak, dan ia menerima instruksi yang jelas tentang apa yang sebenarnya perlu dilakukan.
• Fokus pada tugas pengguna dan tingkat melek teknisnya.
Misalnya, dalam dokumentasi untuk rata-rata pengguna, alih-alih menulis "Buat Mesin Virtual", Anda harus menulis "Instal Windows atau OS lainnya", sebagai istilah " mesin virtual ”masih jauh dari diketahui semua orang. Atau contoh lain - topik yang menjelaskan cara membuat pintasan keyboard cepat, lebih baik memanggil "Konfigurasi Pintasan Keyboard" daripada "Pengaturan Keyboard".
Meskipun apa gunanya, bagi sebagian besar pembaca Habr akan lebih jelas untuk "Mengkonfigurasi pintasan", tetapi pertanyaannya sudah seberapa banyak istilah seperti itu sesuai dalam terminologi resmi saat ini :)
• Jika ini mungkin tidak jelas, jelaskan mengapa pengguna mungkin perlu melakukan tugas tertentu.
Sebagai contoh:
• Saat menjelaskan, coba gunakan kata-kata yang digunakan pengguna setiap hari dalam pidatonya. Jika istilah yang secara teknis rumit dapat diganti dengan kata-kata yang lebih sederhana, selalu coba gunakan kata-kata yang lebih sederhana.
Misalnya, "transparan" bukan "transparan". Jika Anda memberi contoh dari bahasa Inggris, gunakan "gunakan" alih-alih "manfaatkan".
2)
Cobalah untuk memberikan semua informasi yang diperlukan tanpa kata-kata yang tidak perlu“Duta besar dari pulau Samos datang ke Sparta untuk meminta bantuan. Mereka membuat pidato yang panjang dan indah. Spartan berkata: "Setelah mendengarkan sampai akhir, kami lupa awal, dan lupa awal, kami tidak mengerti akhirnya." Samosets cerdik. Keesokan harinya, mereka datang ke pertemuan dengan tas kosong dan hanya mengatakan empat kata: "Ada tas, tidak ada tepung." Orang Sparta memarahi mereka - dua kata sudah cukup: "tidak ada tepung," tetapi mereka senang dengan kecerdasan cepat dan berjanji untuk membantu. "Jika Anda menggambarkan fungsionalitas terlalu lama - tidak ada yang akan membacanya. Tapi itu sepenuhnya "dalam Spartan" juga, karena jika terlalu sedikit ditulis akan ada pertanyaan dan keraguan, pengguna akan mulai menarik tim pendukung. Secara umum, penting untuk menjaga keseimbangan.
Untuk membantu pengguna menemukan semua informasi yang mereka butuhkan dan pada saat yang sama menjelaskan setiap bagian sesingkat mungkin:
- Fokus pada informasi paling penting yang diperlukan untuk menyelesaikan masalah yang dijelaskan dalam topik. Jika beberapa detail tidak diperlukan untuk tugas tersebut, jangan jelaskan.
- Tidak perlu mendokumentasikan setiap klik. Jika semuanya jelas di antarmuka, biarkan pengguna mencari tahu sendiri. Misalnya, alih-alih mendokumentasikan setiap langkah instalasi program, lebih baik menulis: "Untuk menginstal program, ikuti instruksi di layar." Jika, sebagai tahap terakhir dari suatu prosedur, Anda harus mengklik OK, ini juga tidak layak dijelaskan.
- Alih-alih memberikan semua informasi dalam satu topik, tunjukkan pada pengguna di mana Anda dapat membaca informasi tambahan menggunakan tautan ke topik lain, tautan ke sumber daya eksternal, atau masukkan bagian "Informasi Terkait" di bagian akhir, yang akan berisi tautan ke topik yang terkait dengan apa yang dijelaskan di layar.
- Jika tugas yang panjang dapat dibagi menjadi beberapa tahap atau subtugas, yang masing-masing merupakan tugas yang terpisah, pisahkan topik ke bagian yang sesuai atau buat bagian dalam panduan, yang terdiri dari topik yang menggambarkan setiap tahap. Dalam hal ini, jangan lupa untuk menyisipkan tautan ke topik terkait.
- Jika tugas (misalnya, memulai mesin virtual) dapat dilakukan dalam beberapa cara, tidak perlu untuk menggambarkan semuanya. Cukuplah menyebutkan cara tercepat dan termudah. Jika Anda masih berpikir bahwa itu berguna bagi pengguna untuk mengetahui tentang metode lain, jelaskan di akhir (dalam bahasa Inggris - Outro) topik.
3)
Jangan ulangi informasi yang sama di halaman
Alih-alih mengulangi informasi dalam setiap topik yang sudah dijelaskan dalam beberapa topik lain, lebih baik merujuk bahwa deskripsi yang lebih rinci dapat ditemukan dalam topik seperti itu, atau cukup berikan tautan ke situ.
4)
Menarik perhatian pengguna dengan benar
Ketika deskripsi perlu menarik perhatian pengguna, kata-kata pengantar berikut digunakan - "Perhatian!" (dalam bahasa Inggris - Peringatan!), "Penting:" (dalam bahasa Inggris - Penting :) dan "Catatan:" (dalam bahasa Inggris - Catatan :).
Setiap kata ini menyiratkan tingkat "kepentingan" sendiri.
Agar tidak menyaring pengguna dengan sia-sia, gunakan setiap istilah dengan benar:
- Gunakan Perhatian! (Peringatan! Dalam bahasa Inggris) untuk menunjukkan situasi berbahaya yang, jika tidak dihindari, dapat mengakibatkan kehilangan data, kerusakan komponen, atau kerusakan lainnya.
- Gunakan "Penting:" (dalam bahasa Inggris - Penting :) untuk menunjukkan situasi yang signifikan dan berpotensi bermasalah, yang, bagaimanapun, tidak dapat menyebabkan kerusakan fisik, kerusakan atau kehilangan data.
- Gunakan "Catatan:" (Catatan :) untuk memberikan informasi tambahan yang terkait dengan topik ini. Meskipun penyisipan seperti itu melepaskan pengguna dari tugas saat ini, itu bisa bermanfaat.
Sebagai contoh:
Untuk membuka konfigurasi mesin virtual, klik Tindakan> Konfigurasikan.
Catatan: Mesin virtual harus dimatikan.
Gunakan catatan "Catatan:" hemat - jika Anda memasukkannya terlalu sering, itu akan menyumbat teks, dan berhenti memperhatikannya.
Jika memungkinkan, masukkan "Perhatian!", "Penting:" dan "Catatan:" di awal topik sehingga pengguna mengetahui hal ini sebelum mulai melakukan prosedur apa pun. Namun, jika informasi hanya merujuk pada langkah tertentu, masukkan setelah langkah ini.
Contoh:
Dilanjutkan ...(di bagian selanjutnya dari artikel ini kita akan membahas topik yang lebih detail yang menjelaskan cara menyelesaikan masalah tertentu)