Saran buruk: bagaimana cara menulis dokumentasi teknis? Bagian Tiga dan Terakhir

Kiat untuk menulis dokumentasi teknis yang kompeten untuk pengguna.
Bagian 3 (final)

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



Kali ini kami akan mempertimbangkan secara lebih rinci:

• topik konseptual (halaman konsep);
• topik referensi (halaman referensi);
• topik yang menjelaskan cara mengatasi masalah (halaman pemecahan masalah);
• di mana dan bagaimana menggunakan tangkapan layar;
• dan juga memberikan beberapa tips bagi mereka yang menulis dokumentasi dalam bahasa Inggris.

Bagian sebelumnya: pendekatan kami terhadap dokumentasi dan lokalisasi; tips dokumentasi bagian 1 dan bagian 2 .

Topik konseptual (halaman konsep)

Topik seperti itu diperlukan untuk memberi pengguna informasi teknis tambahan dan dengan demikian tidak membebani topik tugas.

Harap dicatat bahwa mereka harus berisi informasi tambahan yang tepat, tetapi bukan cara untuk menyelesaikan masalah.

Topik konseptual baik digunakan untuk:

• katakan bagaimana proses tertentu bekerja;
• Jelaskan apa saja fitur baru yang ditambahkan dalam versi produk ini;
• memberi pengguna informasi tambahan yang akan membantunya mengambil keputusan;
• Katakan apa yang dapat dilakukan pengguna di aplikasi Anda.

Misalnya, topik "Tentang Mesin Virtual" dapat menjelaskan apa itu dan bagaimana cara kerjanya. Tetapi topik ini tidak boleh berisi instruksi tentang cara membuat mesin virtual - ini harus dijelaskan dalam topik tugas.

Dengan demikian, pengguna yang berpengalaman, saat membaca topik tugas, tidak akan mengeluh: "Mengapa Anda melukis saya apa itu, saya sudah tahu ...". Dan mereka yang tidak tahu akan melihat tautan ke topik konseptual dan membaca.

Biasanya, judul topik konseptual dimulai dengan:

• "Tentang (sesuatu)" ("Tentang Mesin Virtual");
• "Apa itu ...?" ("Apa itu Mesin Virtual?");
• "Bagaimana cara kerjanya (sesuatu)?" ("Bagaimana Mesin Virtual Bekerja?");
• “Memahami Dasar-Dasar Mesin Virtual”, dll.

Berikut adalah contoh topik konseptual dari dokumentasi bahasa Inggris:



Topik referensi (halaman referensi) :

Topik semacam itu menjelaskan berbagai informasi referensi yang dapat dirujuk pengguna jika perlu.

Contoh bagus dari topik tersebut adalah:

• "Glosarium" di akhir panduan;
• topik di mana Anda menjelaskan item apa yang tersedia di menu dan apa yang mereka lakukan, pintasan keyboard apa yang dapat Anda gunakan saat bekerja dengan program, ikon apa yang tersedia di bilah tugas, dll.

Berikut adalah contoh topik yang menjelaskan ikon GUI:



Topik yang menjelaskan cara mengatasi masalah (halaman pemecahan masalah)


Topik semacam itu membantu pengguna mengatasi hambatan atau menyelesaikan masalah. Topik pemecahan masalah mungkin memiliki skenario berikut:

• Pengguna memiliki masalah dan ingin menyelesaikannya. Misalnya, "Perangkat USB Saya Tidak Bekerja di Mesin Virtual".
• Pengguna mencoba melakukan sesuatu dan gagal. Misalnya, "Saya Tidak Dapat Mengaktifkan Desktop Paralel" ("Saya Tidak Bisa Mengaktifkan Desktop Paralel").
• Ada beberapa kondisi atau kondisi yang ingin diubah pengguna. Misalnya, "Windows lambat" ("Windows Tampaknya Lambat").

Apa yang ada dan yang bukan pemecahan masalah :

Jika pengguna ingin melakukan sesuatu, tetapi tidak tahu caranya, ini harus dijelaskan bukan dalam pemecahan masalah, tetapi dalam topik tugas.

Pemecahan masalah menyiratkan bahwa pengguna mencoba melakukan sesuatu (sesuai dengan instruksi topik tugas), tetapi ada beberapa masalah, dan pengguna tidak tahu bagaimana menyelesaikannya.

Misalnya, topik yang menjelaskan cara menggunakan drive eksternal di sistem operasi tamu adalah topik tugas.

Dan topik yang menjelaskan kemungkinan masalah - “Saya mengalami masalah saat menyambungkan hard disk” - adalah topik pemecahan masalah. Isinya menyiratkan bahwa pengguna mengikuti instruksi, tetapi karena alasan tertentu ia tidak berhasil.

Jika Anda menulis topik tugas, dan beberapa langkah dalam instruksi dapat menyebabkan sedikit kesulitan, Anda dapat menggambarkannya dalam langkah atau topik yang sama. Untuk kesulitan kecil, tidak perlu menulis topik pemecahan masalah yang terpisah.

Misalnya, di akhir topik yang menjelaskan cara mengubah pintasan keyboard, Anda dapat menambahkan: "Beberapa kombinasi tombol tidak dapat diedit atau dihapus".

Topik Pemecahan Masalah

Biasanya, topik pemecahan masalah memiliki struktur yang mirip dengan topik tugas.

Mereka terdiri dari:

• Judul ("judul")
• Bagian pengantar ("intro")
• Frasa pengantar, setelah itu langkah bernomor atau informasi yang diperlukan ("langkah menuju") dimulai
• Informasi yang diperlukan untuk menyelesaikan masalah ("langkah menuju solusi")
• Bagian terakhir ("outro")

Judul (judul halaman)

Ini bagus ketika tajuk topik pemecahan masalah mengungkapkan masalah orang pertama pengguna. Sebagai contoh:

• “Saya Tidak Dapat Mengaktifkan Desktop Paralel” (“Saya Tidak Dapat Mengaktifkan Desktop Paralel”)
• "Windows lambat" ("Windows Sepertinya Lambat")
• “Pesan Berkata 'Tidak Ada Mesin Virtual Terdeteksi'” muncul

Jika Anda menulis dokumentasi dalam bahasa Inggris, Anda harus menggunakan kapitalisasi judul-judul dalam judul (untuk kapitalisasi, lihat detail di akhir artikel):

Kanan: Perangkat USB Saya Tidak Berfungsi

Salah: Perangkat USB saya tidak berfungsi

Pendahuluan (intro)

Segera setelah tajuk, berikan pengguna informasi yang perlu mereka ketahui terlebih dahulu.

Sebagai contoh:

• Jelaskan kemungkinan penyebab masalahnya. Jika ada banyak alasan, jelaskan semua yang mungkin.
• Terkadang Anda dapat menjelaskan secara umum apa yang perlu dilakukan untuk menyelesaikan masalah. Secara umum - instruksi terperinci harus diberikan dalam langkah-langkah penyelesaian.

Frasa pengantar (heading langkah)

Sebelum urutan langkah-langkah yang perlu Anda ambil untuk menyelesaikan masalah, tulislah kata pengantar. Jangan lupa meletakkan tanda titik dua di bagian ujung.

Jika solusi untuk masalah ini adalah serangkaian tindakan berurutan:

Dalam kasus seperti itu, frasa pengantar harus dilakukan sesuai dengan prinsip yang sama seperti untuk topik tugas (lihat bagian kedua tips), yaitu, gunakan kata-kata yang sama seperti dalam perumusan tugas.

Misalnya, Anda menulis topik pemecahan masalah di mana Anda menjelaskan mengapa pengguna tidak dapat membuka konfigurasi mesin virtual (item menu berwarna abu-abu dan tidak aktif):

Judul: "Saya Tidak Bisa Membuka Pengaturan Mesin Virtual"

Pendahuluan: "Jika Anda tidak dapat membuka pengaturan mesin virtual (item menu berwarna abu-abu), maka kemungkinan besar alasannya adalah bahwa mesin virtual tidak dimatikan."

Selanjutnya, frasa pengantar: "Untuk membuka pengaturan mesin virtual:" (kata-kata yang sama digunakan dalam frasa ini seperti dalam perumusan tugas yang akan dilakukan)

Dan kemudian ada langkah - 1) Pastikan mesin dimatikan. Jika berhasil, klik di sana-sini. 2) Kemudian lakukan ini.

Jika masalah memiliki beberapa solusi:

Dalam kasus seperti itu, frasa pengantar harus berisi kata-kata:

- "coba solusi ini",
- "coba yang berikut",
- "pastikan itu", dll.

Berikut adalah beberapa contoh dari dokumentasi bahasa Inggris:

Judul Halaman: Saya Tidak Dapat Mengaktifkan Parallels Desktop
Meliputi Tugas: Daftar hal yang perlu diperiksa
Step Heading: Jika Anda kesulitan mengaktifkan Parallels Desktop, pastikan bahwa ...

Judul Halaman: Windows Sepertinya Lambat
Meliputi Tugas: Daftar hal yang harus dicoba
Langkah Kepala: Jika kinerja Windows tampaknya lambat, coba yang berikut ...

Judul Halaman: Sebuah Pesan Mengatakan “Tidak Ada Mac yang Terhubung”
Meliputi Tugas: Beberapa hal untuk diperiksa atau dicoba
Step Heading: Jika Anda tidak melihat Mac di daftar Mac

Informasi yang diperlukan untuk menyelesaikan masalah (langkah-langkah menuju solusi)

Bagian ini mencakup segala sesuatu yang perlu diketahui dan / atau dilakukan pengguna.

Jika ada beberapa solusi:
Dalam kasus seperti itu, jelaskan setiap metode menggunakan peluru (lebih lanjut tentang ini di bagian kedua tips). Jika ada metode yang rumit, dan Anda telah menjelaskannya secara terperinci dalam topik lain, cukup berikan tautan.

Jika yang perlu Anda lakukan sudah dijelaskan di suatu tempat di topik lain:
Berikan saja tautan ke topik ini.

Jika tidak ada instruksi khusus, apa yang bisa dilakukan untuk menyelesaikan masalah:
Berikan informasi tambahan yang dapat membantu pengguna untuk mencari tahu apa yang bisa menyebabkan masalah.

Kesimpulan (outro)

Sebagai kesimpulan, Anda dapat memberikan informasi tambahan yang terkait dengan tugas atau kemungkinan solusi untuk masalah tersebut. Anda dapat membaca lebih lanjut tentang menggunakan outro di bagian dua tips .

Menggunakan grafik (tangkapan layar, bagan, diagram, dll.)

Tangkapan layar dan diagram dapat membantu pengguna untuk lebih memahami apa yang tertulis dalam topik.

Kapan menggunakan grafik:

Di bawah setiap langkah, Anda tidak perlu menyisipkan tangkapan layar - pengguna tidak akan tahu ke mana harus mencari, terus-menerus membandingkan layar dan tangkapan layar.

Tangkapan layar harus dimasukkan ketika mereka secara signifikan membantu memahami apa yang tertulis dalam instruksi.

Sebagai contoh:

• Ketika Anda perlu menunjukkan tombol atau ikon yang tidak memiliki nama di dalam gua, atau tidak langsung menyentuh mata, atau ada beberapa yang serupa di layar;
• Ketika Anda perlu memberikan konteks untuk tugas atau penjelasan visual yang jelas tentang bagaimana dan apa yang akan terlihat pada akhirnya;
• Jika tangkapan layar memungkinkan Anda untuk dengan cepat memahami atau menjelaskan sesuatu yang akan membutuhkan penjelasan yang terlalu panjang dan rumit dalam kata-kata.

Di mana dan bagaimana menempatkan jadwal:

Di bawah ini adalah beberapa rekomendasi di mana dan bagaimana menempatkan gambar pada halaman.

1) Jika tangkapan layar mencerminkan informasi konseptual atau hasil tugas, Anda dapat memasukkannya di atau setelah intro.

Berikut adalah contoh dari dokumentasi bahasa Inggris, yang menunjukkan topik yang menjelaskan mode berjendela Windows. Tangkapan layar yang menunjukkan apa yang akan terjadi setelah sakelar tersebut dimasukkan setelah pendahuluan dan sebelum instruksi itu sendiri, cara beralih ke mode ini:



2) Jika tangkapan layar mengacu pada langkah spesifik dalam instruksi, masukkan setelah atau di dalam langkah ini:



Jika Anda perlu menyisipkan tangkapan layar tombol, ikon, atau elemen antarmuka lainnya, Anda harus memasukkannya setelah nama elemen ini:



Jangan gunakan gambar untuk menggambarkan hal-hal yang jelas.

Secara khusus, jangan gunakan tangkapan layar untuk menggambarkan:

• Menu
• Ikon, tombol, dan tab yang memiliki nama
• Segala sesuatu yang dapat dengan mudah dan mudah dijelaskan dengan kata-kata.

Kiat tambahan bagi mereka yang menulis dokumentasi dalam bahasa Inggris:


1) Bagaimana cara mengkapitalisasi judul:

kapitalisasi Tersedia tiga gaya kapitalisasi: gaya kalimat, gaya judul, dan semua batas.

• Kapitalisasi gaya kalimat: Baris ini memberikan contoh kapitalisasi gaya kalimat.
• Kapitalisasi judul-gaya: Baris Ini Memberikan Contoh Kapitalisasi Judul-Gaya.
• Semua batas: GARIS INI MENYEDIAKAN CONTOH DARI SEMUA CAPS.

Jangan gunakan semua huruf besar untuk penekanan.

huruf besar (gaya kalimat): Saat Anda menggunakan huruf besar gaya kalimat, huruf besar huruf pertama dari kata pertama, serta huruf pertama dari kata benda dan kata sifat yang tepat.
kapitalisasi (gaya judul): Gunakan kapitalisasi gaya judul untuk judul buku, judul bagian, judul bab, dan judul bagian (kepala teks).

Ikuti aturan ini saat Anda menggunakan huruf besar judul-gaya. Huruf besar setiap kata kecuali:

• Artikel (a, an, the), kecuali artikel adalah kata pertama atau mengikuti tanda titik dua
• Konjungsi koordinasi (dan, tetapi, atau, tidak, untuk, belum, dan sebagainya)
• Kata untuk infinitif (Cara Menghubungkan Printer Anda)
• Kata as, terlepas dari bagian ucapannya
• Kata-kata yang selalu dimulai dengan huruf kecil, seperti iPhone dan iPad.
• Preposisi empat huruf atau lebih sedikit (pada, oleh, untuk, dari, ke, ke, dari, ke, ke, ke luar, ke atas, ke, ke atas, dan dengan), kecuali bila kata tersebut merupakan bagian dari frasa kata kerja. Sebagai contoh:
  
  Mulai KomputerLog
  Masuk ke ServerGet
  Dimulai dengan Parallels Desktop

Kapitalisasi:

• Kata pertama dan terakhir, terlepas dari bagian pidato:
Untuk pengguna linux

Untuk Apa Parallels Tools

• Kata kedua dalam senyawa ditulis dgn tanda penghubung:

Benar: Acara Tingkat Tinggi, Pengalamatan 32-Bit
Salah: Acara Tingkat Tinggi, Pengalamatan 32-bit
Pengecualian: Built-in, Plug-in

• Kata-kata Are, If, Is, It, Than, That, dan This

2) Cara menggunakan kata "klik":

klik Gunakan klik untuk menjelaskan tindakan memposisikan pointer pada objek di layar dan dengan singkat menekan dan melepaskan tombol mouse. Jangan gunakan klik. Karena sebagian besar pengguna tahu apa itu mengklik, Anda perlu mendefinisikannya hanya dalam dokumentasi yang dirancang untuk pengguna pemula, seperti tutorial.
Benar: Klik Mac jika Anda ingin menggunakan perangkat USB dengan Mac OS X.

Salah: Arahkan ke Mac dan klik jika Anda ingin menggunakan perangkat USB di Mac OS X.
klik Jangan gunakan; gunakan klik.

3) Email atau email?

Gunakan email. Jangan gunakan email.

4) Jika atau apakah?

Gunakan jika untuk mengekspresikan suatu kondisi. Gunakan apakah akan mengekspresikan alternatif.
Benar: Periksa apakah Parallels Tools telah diinstal.
Salah: Periksa apakah Parallels Tools telah diinstal.
Benar: Klik Mac jika Anda ingin menggunakan perangkat USB dengan Mac OS X.

5) Cara menggunakan nama produk:

Ikuti gaya huruf besar pada kemasan produk. Gunakan nama produk lengkap untuk kemunculan pertamanya dalam bagian teks (misalnya, bab). Setelah itu, jika berlaku gunakan versi singkat dari nama produk.

Misalnya: Parallels Desktop 14 untuk Mac: Pada kemunculan pertama dalam bagian teks, gunakan Parallels Desktop 14 untuk Mac.

Pada kejadian berikutnya, gunakan Parallels Desktop.

Kesimpulan

Dalam 3 bagian manual ini, kami mencoba menyusun, merangkum, dan menyusun tip yang akan membantu membuat dokumentasi Anda lebih mudah dan lebih mudah dipahami.

Kami tidak bersikeras bahwa menulis diperlukan dengan cara ini - ada banyak pendekatan untuk dokumentasi dan teknik. Lihatlah pengaturan dan gunakan yang sesuai dengan Anda.

Terima kasih banyak atas perhatian dan minat Anda!