Saran buruk: bagaimana cara menulis dokumentasi teknis? Bagian dua

Kiat untuk menulis dokumentasi teknis yang kompeten untuk pengguna.
Bagian 2

Kelanjutan manual penulis teknis kami Andrei Starovoitov, yang akan membantu membuat dokumentasi pengguna Anda lebih mudah dan lebih mudah dipahami.

Anda dapat membaca bagian awal artikel di sini , tetapi kami menjelaskan proses mendokumentasikan dan melokalkan produk kami sebelumnya dalam artikel ini.

Pada bagian ini, kami akan menganalisis secara terperinci topik-topik yang sebagian besar terdiri dari dokumentasi pengguna (terutama Panduan Pengguna) - yaitu, topik - topik tugas yang menjelaskan cara menyelesaikan masalah tertentu.



Berapa banyak tugas yang harus dijelaskan dalam topik - satu atau lebih?

Topik tugas dapat menjelaskan satu tugas - "Luncurkan Aplikasi Windows" ("Luncurkan Aplikasi Windows"), serta beberapa tugas terkait. Misalnya, topik "Optimalkan Kinerja" dapat terdiri dari bagian berikut: "Secara Otomatis Menghemat Ruang Disk" dan "Tune MacBook Anda untuk Kinerja yang Lebih Baik atau Hemat Baterai" ("Optimalkan Your MacBook untuk Masa Pakai Baterai Lebih Lama atau Kinerja Lebih Tinggi ”).

Kita harus mencoba menulis topik tugas berdasarkan prinsip: satu topik - satu tugas. Benar, ada pengecualian - jika Anda memiliki dua tugas yang berlawanan dalam tindakan, maka mereka harus dijelaskan dalam satu topik. Misalnya, jika Anda perlu menjelaskan cara beralih mesin virtual ke mode layar penuh dan cara keluar nanti, Anda perlu melakukan ini dalam topik yang sama.
Jika Anda perlu menjelaskan beberapa tugas terkait, maka ini juga dapat dilakukan dalam satu topik, asalkan deskripsi mereka tidak panjang.

Bagian dari topik tugas

Topik tugas terdiri dari:

• Tajuk
• Bagian pengantar (dalam bahasa Inggris "intro")
• Frasa, yang mengarah ke deskripsi tentang apa yang sebenarnya harus dilakukan pengguna (dalam bahasa Inggris "step step")
• Langkah bernomor atau buletinning (dalam bahasa Inggris "langkah bernomor atau berpoin")
• Bagian terakhir (dalam bahasa Inggris "outro")

Kadang-kadang terjadi bahwa topik tugas tidak mengandung semua bagian di atas - misalnya, tidak perlu memasukkan Intro atau Outro. Selanjutnya kita akan membahas lebih detail pada setiap bagian dari topik.

Berita utama

Kita harus mencoba membuat judul sedemikian sehingga pengguna segera mengerti apa yang akan ditulis dalam topik.

Buat berita utama luas, tetapi tidak terlalu lama pada saat yang sama. Header panjang mungkin tidak sepenuhnya ditampilkan di beberapa browser atau Apple Help Viewer.

Saat menulis judul, gunakan imperatif ("Lakukan ini")

Misalnya, "Mengatur Printer Menggunakan Bonjour".

Jangan gunakan imperatif dalam nama topik yang tidak menjelaskan cara menyelesaikan masalah.

Gunakan kata-kata yang mudah digunakan dalam nama topik, jangan berkonsentrasi pada elemen antarmuka.

Pengguna tidak ingin memahami fitur, istilah, elemen antarmuka, dll. - ia harus menyelesaikan masalah spesifiknya. Oleh karena itu, atas nama topik, coba gunakan kata-kata yang akan digunakan sendiri oleh pengguna. Misalnya, jika Anda memanggil topik "Mengatur Mac Anda untuk Menggunakan Aplikasi Windows", itu akan jauh lebih dimengerti bagi pengguna daripada topik "Tentang Mesin Virtual".

Cobalah untuk merumuskan tujuan karena pengguna mungkin akan melakukannya. Misalnya, alih-alih "Mulai Sesi Jarak Jauh" - lebih baik beri nama topik "Mulai Mengontrol Windows Jarak Jauh".

Jika Anda perlu menggunakan istilah yang secara teknis rumit atau nama antarmuka, maka ini sebaiknya dilakukan bukan di header, tetapi dalam pengantar topik.

Jika Anda menulis dokumentasi dalam bahasa Inggris, kata-kata dalam judul harus dimulai dengan huruf kapital

Kanan : Mengatur Mac Anda untuk Menggunakan Aplikasi Windows

Salah : Siapkan Mac Anda untuk menggunakan aplikasi Windows

(Kami akan membahas kapitalisasi judul secara lebih rinci di bagian selanjutnya dari manual ini).

Intro (Intro)

Di bagian pengantar, yang langsung muncul setelah header, Anda harus menulis apa yang perlu diketahui pengguna sebelum ia mulai melakukan tugas.

Prolog dapat berisi:

• Informasi umum tambahan: apa yang dapat dilakukan pengguna.
• Motivasi : mengapa pengguna mungkin perlu melakukan satu atau tindakan lain. Berikut adalah contoh bagian pengantar yang menjelaskan mengapa Anda mungkin perlu mengunduh dan menggunakan mesin virtual yang sudah jadi:

Gunakan mesin virtual yang tidak tersedia

Jika Anda tidak punya waktu untuk membuat mesin virtual baru dengan konfigurasi yang diperlukan, Anda dapat mengunduh mesin virtual yang sudah selesai dengan konfigurasi pra-konfigurasi.

• Peringatan tentang segala kemungkinan kerusakan pada perangkat keras, perangkat lunak, atau hilangnya data yang mungkin terjadi saat pengguna melakukan suatu tindakan.
• Informasi penting tentang potensi masalah atau kesulitan yang, meskipun tidak mengakibatkan kerusakan pada kesehatan, peralatan, atau kehilangan data, dapat terjadi selama pelaksanaan tugas.
• Penjelasan: apa arti istilah ini atau itu atau bagaimana fitur apa pun bekerja.

Misalnya, jika pengguna Parallels Desktop ingin bekerja dengan macOS dan Windows pada saat yang sama, seolah-olah itu adalah satu sistem operasi, maka di bagian pengantar Anda dapat berbicara tentang "mode koherensi" untuk mempersiapkan pengguna untuk persyaratan yang selanjutnya akan digunakan dalam topik.

• Informasi tentang kondisi tambahan : misalnya, dalam topik yang menjelaskan cara menghubungkan printer melalui Bonjour, intro dapat memberi tahu Anda versi Windows yang mendukung Bonjour.
• Kondisi yang diperlukan untuk tugas saat ini : jika sebelum mulai melakukan tugas yang dijelaskan dalam topik, pengguna perlu melakukan atau memeriksa sesuatu yang lain, maka ini harus disebutkan di bagian pengantar. Dan alangkah baiknya untuk memberikan tautan ke topik-topik yang dijelaskan sehingga pengguna dapat dengan cepat menemukan dan membaca.

Jangan menyisipkan prolog di tempat yang tidak diperlukan.

Meskipun bagian pengantar memberikan informasi bermanfaat tambahan, terkadang semuanya jelas dari judulnya sendiri. Dalam kasus seperti itu, Anda tidak perlu membuat teks pengantar, jika hanya itu.

Sebagai contoh:

Luncurkan aplikasi Mac melalui menu Start

Buka menu Start Windows dan lakukan salah satu dari yang berikut:

• Klik Semua Program> Parallels Shared Applications dan pilih aplikasi yang Anda inginkan.
• Masukkan nama aplikasi di bidang pencarian dan pilih aplikasi yang diinginkan dari opsi yang diusulkan.

Jangan membuat prolog terlalu lama

Pendahuluan terlalu lama mengganggu pengguna. Dalam kasus seperti itu, pengguna sering melewatkannya dan langsung ke daftar langkah-langkah spesifik.

Jika bagian pengantar terlalu besar, Anda perlu menyebutkan yang utama dan memberikan tautan ke halaman konseptual terpisah atau halaman referensi, di mana semuanya sudah akan dijelaskan secara rinci.

Terkadang, untuk memudahkan membaca teks panjang secara visual di bagian pengantar, peluru dapat digunakan. Sebagai contoh:



Jangan beri tahu dalam pengantar bagaimana menyelesaikan tugas

Prolog bukan untuk ini. Apa yang perlu dilakukan, di mana dan bagaimana - perlu untuk menggambarkan hanya nanti, setelah bagian pengantar.

Namun, dalam kasus yang jarang terjadi, Anda mungkin perlu memberi tahu pengguna apa yang mereka butuhkan untuk menyelesaikan tugas. Pada contoh di bawah ini, bagian pengantar memberi tahu pengguna apa yang mereka butuhkan untuk menyelesaikan tugas yang dijelaskan dalam topik.



Jangan menggambarkan hasil tugas di bagian pengantar.

Ini harus dilakukan di bagian akhir ( Outro ).

Ungkapan sebelum instruksi (Step Heading)

Setelah Intro, Anda perlu memasukkan frasa “pengantar” (dalam bahasa Inggris - “step step”), yang mengarahkan pengguna ke instruksi: apa yang sebenarnya perlu dilakukan untuk mencapai satu atau hasil yang lain.

Misalnya, di Intro kami menulis: “ Jika Anda memiliki disk instalasi dan kunci aktivasi, Anda dapat menggunakannya untuk menginstal Windows di mesin virtual. "

Setelah Pengenalan, tuju langkah: " Untuk menginstal Windows: "

Dan kemudian langkah-langkahnya sendiri:

1) Klik di sini.
2) Pilih ini.
3) Dan seterusnya ...

Harap dicatat: jika tidak ada Intro dalam topik ini, maka langkah pos adalah opsional.

Jika topik tersebut menjelaskan langkah-langkah berurutan, maka pos langkah harus terlihat seperti " Untuk melakukan sesuatu:" ("Untuk melakukan X:").
Misalnya: "Untuk beralih ke mode Layar Penuh:" ("Untuk memulai Windows:") atau " Untuk beralih ke mode layar penuh:" .

Jangan lupa meletakkan tanda titik dua di bagian ujung

Jika tajuk menggunakan kata-kata yang mudah digunakan, dan Anda harus menggunakan istilah teknis yang kompleks atau nama-nama elemen antarmuka dalam instruksi, Anda dapat melakukan hal berikut: di bagian pengantar Anda menjelaskan apa arti istilah tersebut, dan pada tajuk langkah Anda sudah menggunakannya secara aktif.

Sebagai contoh:

1) kami membuat header lebih jelas bagi pengguna:

" Mengatur Windows untuk Mengambil Layar Utuh"

2) Selanjutnya dalam Pengenalan kami memperkenalkan istilah "mode Layar Penuh".

3) Setelah ini, dalam langkah tajuk Anda sudah dapat menggunakan istilah ini tanpa takut itu tidak akan dimengerti oleh pengguna:

" Untuk memasuki Layar Penuh:" ("Untuk memasuki Layar Penuh:")

Jika langkah-langkah yang dijelaskan dalam topik bukanlah urutan tindakan, tetapi beberapa cara untuk mencapai tujuan, maka langkah langkah harus dilakukan sebagai berikut: "Berikut adalah beberapa cara untuk melakukan sesuatu:" ("Berikut adalah cara untuk melakukan X:") atau " Untuk melakukan ini, lakukan salah satu dari yang berikut: " (" Untuk melakukan X, lakukan salah satu dari yang berikut: ").

Misalnya, "Berikut adalah cara untuk mematikan Windows:") atau " Untuk menghubungkan printer, lakukan salah satu dari yang berikut: " ("Untuk menghubungkan printer, lakukan salah satu dari yang berikut: ").

Saat membuat heading langkah, Anda perlu menggunakan kata-kata yang mencerminkan tugas yang dijelaskan dalam topik tugas. Berikut ini beberapa contoh dalam bahasa Inggris:

Judul Halaman : Instal Windows dari CD Instalasi.
Tugas Meliputi : Menginstal Windows menggunakan disk instalasi.
Step Heading : Untuk menginstal Windows.

Judul Halaman : Sesuaikan Pengaturan Koherensi.
Penutup Tugas : Menyesuaikan bagaimana Windows muncul dan berperilaku dalam mode Koherensi.
Step Heading: Untuk menyesuaikan mode Koherensi.

Judul Halaman : Mengatur Windows untuk Mengambil Layar Utuh
Penutup Tugas : Memasuki mode layar penuh.
Step Heading : Untuk masuk ke mode Layar Penuh, lakukan salah satu dari yang berikut:

Langkah bernomor

Semua topik yang menjelaskan cara melakukan tugas tertentu berisi instruksi tentang apa yang harus dilakukan. Tindakan-tindakan ini dalam teks biasanya diberi nomor (jika merupakan serangkaian langkah berurutan) atau disorot oleh peluru (jika diusulkan untuk memilih salah satu daftar sesuai kebijaksanaan Anda).

Buat daftar langkah-langkah yang diperlukan sesingkat mungkin.

Pilih dan jelaskan cara termudah dan tercepat untuk menyelesaikan suatu tindakan. Metode alternatif dapat dijelaskan di bagian akhir (Outro) atau di topik tugas lain. Jangan memaksa pengguna untuk membaca instruksi dalam 4 langkah, jika semua hal yang sama dapat dilakukan dengan mengklik satu tombol.

Jika cara termudah adalah melakukan tindakan melalui bilah alat, jelaskan opsi ini. Jika bilah alat dapat dikustomisasi sesuai keinginan Anda, dan Anda ragu, tiba-tiba konfigurasi pengguna bilah alat berbeda dari yang dijelaskan dalam topik, jelaskan semuanya seperti yang dilakukan dengan pengaturan default. Seperti yang ditunjukkan oleh praktik, sebagian besar pengguna biasa jarang mengubah pengaturan "pabrik".

Jika Anda perlu menjelaskan beberapa cara bagaimana melakukan suatu tindakan dalam satu topik :

Jika dalam banyak topik tugas buku Anda, tindakan tertentu diulangi yang dapat dilakukan dengan cara yang berbeda (misalnya, melalui menu atau bilah alat), pilih satu metode dan sebutkan secara berurutan di setiap topik tugas.

Jika ada cara alternatif yang sederhana dan pendek, dan Anda tentu ingin membicarakannya, Anda bisa melakukannya dengan langkah yang sama.

Misalnya: "Untuk membuka konfigurasi mesin virtual, pilih Tindakan> Konfigurasikan atau klik ikon Konfigurasikan di sudut kanan atas.").

Beri nomor langkah yang harus dilakukan berurutan.

Agar tidak mengembang deskripsi dan tidak menyoroti instruksi yang sangat singkat dalam langkah-langkah terpisah (seperti "Klik OK"), Anda dapat menggabungkan 2 tindakan terkait dan terkait dalam satu langkah, seperti yang ditunjukkan di bawah ini:



Gunakan peluru untuk menyoroti tindakan yang tidak konsisten

Terkadang pengguna ditawari beberapa cara untuk memilih cara mencapai tujuan. Dalam kasus seperti itu, opsi yang diusulkan mengeluarkan peluru.

Sebagai contoh:


Jika daftar berisi nama elemen grafis, sorot untuk kejelasan dalam huruf tebal

Jika tindakan yang akan dilakukan oleh pengguna mencantumkan sejumlah elemen dari antarmuka grafis (item menu, daw, dll.), Mulai setiap opsi dari baris baru, sorot nama elemen dalam huruf tebal. Setelah elemen ditandai dengan huruf tebal, beri tanda titik dua, lalu jelaskan deskripsi dalam teks biasa.

Seperti yang ditunjukkan dalam contoh ini:


Jika teks dalam topik merujuk ke berbagai elemen antarmuka berkali-kali, mungkin ada baiknya membuat topik bantuan terpisah di mana elemen-elemen ini akan dijelaskan.

Ini akan sangat berguna jika banyak topik dalam panduan ini merujuk pada elemen yang sama. Dalam hal ini, di awal topik, Anda harus memberikan tautan ke topik referensi di mana elemen yang disebutkan dijelaskan.

Jika elemen ini disebutkan lagi nanti dalam teks, Anda tidak perlu lagi memberikan tautan - hanya satu di awal. Ketika ada banyak tautan dalam topik, ini dapat mempersulit persepsi dan pemahaman tentang apa yang ditulis.

Bagian terakhir (Outro)

Outro adalah informasi akhir yang muncul setelah langkah-langkah bernomor. Cobalah untuk mempersingkat bagian akhir - gunakan tidak lebih dari 3 paragraf, yang masing-masing terdiri dari maksimal 3 kalimat.

Gunakan Outro untuk menjelaskan hasil atau konsekuensi dari tindakan ini.

Contoh hasil atau konsekuensi mungkin:

• Informasi tentang di mana file diinstal;

• Muncul pesan yang akan membutuhkan tindakan tambahan dari pengguna;

• Pengaturan yang harus diganti oleh pengguna setelah tindakan yang dijelaskan selesai.

Misalnya, bagian terakhir dari topik tentang cara membuat Parallels Access hanya berfungsi di Wi-Fi, mengatakan yang berikut: " Jika Anda mengonfigurasi Parallels Access hanya untuk bekerja di Wi-Fi dan tidak ada jaringan nirkabel yang terdeteksi saat ini, sebuah pesan muncul menanyakan Anda - Apakah Anda ingin terhubung melalui 3G? ".

Di bagian akhir topik, Anda bisa mendeskripsikan cara alternatif untuk menyelesaikan tugas.

Jika metode alternatif dapat dijelaskan dalam satu kalimat, Anda dapat melakukan ini di bagian akhir topik.

Outro dapat memberikan lebih banyak informasi yang berkaitan dengan tugas saat ini.

Informasi tersebut dapat memberi informasi kepada pengguna tentang apa lagi yang dapat mereka lakukan setelah menyelesaikan tugas yang dijelaskan.

Dalam contoh berikut, topik tersebut menjelaskan cara menemukan file dari mesin virtual di macOS Finder. Dan pada bagian akhir dari topik menjelaskan apa lagi yang dapat dilakukan pengguna dengan file setelah file ditemukan.



Di Outro, Anda dapat menjelaskan informasi tambahan yang hanya dibutuhkan sebagian pengguna.

Misalnya, di bagian akhir topik tentang mengintegrasikan mesin virtual Windows ke dalam macOS, Anda dapat menulis yang berikut ini: "Jika Anda memiliki MacBook Pro 2016 atau lebih baru, Anda dapat bekerja dengan beberapa aplikasi Windows menggunakan Touch Bar"


Hancurkan tugas-tugas panjang menjadi tahapan pendek

Pada dasarnya, topik tugas pendek dan pas di satu halaman. Namun, jika beberapa tugas yang rumit dan sangat panjang dijelaskan, yang dapat dibagi menjadi tahapan, tahapan, dan prosedur, ada baiknya memisahkan informasi secara logis dan menggambarkan setiap tahap dalam topik yang terpisah sehingga deskripsi terlihat lebih sederhana, lebih baik dibaca dan dipahami.

Berikut ini adalah contoh dari isi Panduan Pengguna Desktop Parallels. Tangkapan layar memperlihatkan bab yang menjelaskan berbagai cara untuk menginstal Windows di mesin virtual. Dan salah satu cara - cara mengimpor data dari komputer jarak jauh - dibagi menjadi beberapa topik.



Dilanjutkan ...

(di bagian selanjutnya kita akan berbicara lebih banyak tentang topik konseptual dan referensi dan topik yang membantu menyelesaikan masalah)