50 pertanyaan untuk mengerjakan dokumentasi

Tidak peduli seberapa keras perancang UX mencoba, seseorang dari jalanan tidak akan dapat menemukan antarmuka kontrol pesawat ruang angkasa tanpa petunjuk. Dan bahkan tidak dari jalan. Hanya karena roketnya besar dan ada banyak pengaturan.

Kami membuat produk lebih sederhana daripada perangkat lunak untuk roket, tetapi secara teknis masih canggih. Kami berusaha sangat keras sehingga antarmuka dari versi baru itu sederhana, tetapi kami menyadari bahwa akan selalu ada pengguna yang tidak akan mengerti sesuatu dan pergi ke dokumentasi. Karena itu, harus ada dermaga, dan agar tidak merusak kesan produk, itu harus berguna dan nyaman.

Kami memiliki enam produk, dokumentasi yang sejak awal perusahaan ditulis oleh pengembang. Selama setengah tahun kami telah menulis ulang artikel lama dan menulis artikel baru . Di bawah cut - 50 pertanyaan yang membantu kami melakukan ini dengan baik. Tapi untuk awalnya, sedikit perkenalan.

Mengapa dokumentasi itu penting, dan siapa yang harus melakukannya

Membuat dermaga yang bagus itu sulit. Di suatu tempat departemen besar analis, penulis dan editor bekerja di sana, dan di suatu tempat pengembang menulis ke dermaga (selesai - dijelaskan).

Kami memiliki dua penulis teknis tentang enam produk dengan beberapa versi. Ini tidak cukup, jadi manajer produk, penguji, garis pertama dukungan dan pemasaran bekerja di dermaga. Mereka tidak menulis artikel, tetapi membantu memahami produk dan tugas klien, memilih topik dan mengumpulkan informasi, memeriksa konten dan desain artikel yang sudah selesai. Bersama-sama kita membuat dermaga menjadi lebih baik.

Jika Anda memiliki departemen penulis kecil, rekrut staf dari departemen lain. Jika mereka tidak tertarik, berikan argumen dari daftar di bawah ini. Dukungan pertama, pemasaran kedua dan ketiga dan pemasaran produk. Jadi mengapa dokumentasi itu penting?

1. Faktor pendukung . Alasan pertama dan paling jelas. Jika dokumentasinya bagus, sebagian besar pelanggan akan menyelesaikan masalah tanpa menghubungi dukungan. Dukungan yang tersisa akan melemparkan tautan ke instruksi atau dengan cepat menelusuri sendiri. Dokumentasi lengkap dapat digunakan untuk membuat bot obrolan. Semua ini mengurangi waktu respons kepada pelanggan, meningkatkan kepuasan mereka, dan juga mengurangi biaya dukungan.
2. Faktor pemilihan . Dokumentasi memengaruhi pilihan klien bersama dengan harga, kenyamanan, fungsionalitas. Ini dikonfirmasi oleh penelitian kami dan umpan balik dari pengguna ISPmanager dan DCImanager . Dalam hal ini, dermaga tidak lagi menjadi kebutuhan dukungan, tetapi menjadi keunggulan kompetitif, bagian dari pemasaran.
3. Faktor loyalitas . Jika klien pergi tanpa memahami dok di awal atau dalam proses, ini merupakan masalah. Menarik pelanggan terlalu mahal untuk hilang karena artikel yang buruk.

Cara membuat dokumentasi yang bagus

Tentukan tujuan . Ini adalah rasa sakit yang paling. Menjelaskan fitur hanya demi deskripsi atau mengomentari sebuah antarmuka bukanlah tujuannya. Tujuan selalu merupakan tindakan yang bermanfaat. Apa yang harus diketahui pengguna, admin, atau pengembang dan dapat dibaca setelah membaca artikel? Misalnya, buat situs dan ikat domain ke sana, keluarkan sertifikat SSL, konfigurasikan cadangan, dll. Yaitu, selesaikan masalah Anda.

Kenali audiens . Kami membagi pelanggan menjadi pengguna, administrator dan pengembang. Tetapi ini tidak cukup untuk membuat teks yang bermanfaat. Untuk memahami audiens dengan cepat, Anda dapat mengunjungi UX dan produk, mempelajari permintaan dukungan, dan jawaban mereka tentang topik tersebut, mendengarkan panggilan lini pertama, melihat situs dan blog (pemasaran juga menulis hal-hal yang diperlukan). Dan hanya setelah itu mulai menulis.

Periksa, edit, dan periksa lagi . Penulis teknis harus melakukan pemeriksaan awal. Setelah dia satu lagi. Maka ada baiknya menghubungkan dukungan, pemasaran dan departemen lain dengan audit. Maka Anda perlu memeriksa dengan gaya dan desain manual - kebijakan editorial. Seseorang dari samping atau penulis teknologi lain membiarkannya melakukan proofreading terakhir. Jika Anda memiliki editor, maka dia akan mengambil tahap ini.

Bagikan artikel setelah publikasi . Jika dokumentasi ditulis, kemungkinan besar seseorang membutuhkannya. Tunjukkan pada cahaya dan gunakan secara maksimal: terjemahkan, rujuk ke produk, berikan ke pemasaran, dukungan. Jangan menulis ke meja.

50 pertanyaan untuk dikerjakan di dermaga

Bekerja pada dokumentasi, kami mengulangi kesalahan yang sama. Mereka menghabiskan terlalu banyak waktu untuk memeriksa artikel, dan panduan, yang awalnya tampak seperti obat mujarab, tidak membantu, karena masalahnya ada pada pendekatan dan konten. Agar para penulis teknis dapat membawa artikel itu ke dalam pikiran mereka dengan cepat dan cepat, kami mengumpulkan semua pertanyaan yang selalu kami tanyakan (atau lupa tanyakan) kepada mereka. Gunakan jika menulis dermaga juga.

Tujuan

1. Untuk siapa saya menulis artikel? Siapa pembaca masa depan: pengguna, administrator, pengembang?
2. Tugas apa yang dihadapinya (pekerjaan yang harus dilakukan)? Apakah ada deskripsi orang tersebut?
3. Apa tingkat pelatihan pengguna ini? Apa yang sudah dia ketahui? Apa yang tidak jelas baginya?
4. Bagaimana ini bisa dijelaskan kepada pengguna pemula dan tidak marah dengan penjelasan lanjutan tentang hal-hal dasar?
5. Apa lagi yang perlu dijelaskan kepada pengguna sehingga ia mengerti konten utama artikel?
6. Bagian dokumentasi apa yang cocok untuk artikel ini?
7. Haruskah artikel ini atau bagiannya digandakan di bagian lain?
8. Artikel apa yang harus saya tautkan?
9. Mungkin artikel ini harus disertai dengan instruksi video?

Sumber informasi

10. Apakah pengguna saat ini memiliki masalah dengan topik artikel?
11. Bagaimana dukungan sekarang menjelaskan apa yang perlu dilakukan?
12. Apakah departemen pemasaran menulis artikel dan berita blog tentang topik ini? Bisakah mereka “memata-matai” kata-kata, struktur, dll.?
13. Apakah ada bagian tentang topik ini di situs?
14. Apa yang termasuk dalam skrip UX dan manajer produk? Mengapa itu melakukan ini?
15. Bagaimana pertanyaan ini dijelaskan oleh pesaing?
16. Di bidang apa Anda masih bisa melihat praktik terbaik?

Pemeriksaan Konten

17. Apakah Anda mencapai tujuan artikel?
18. Apakah semuanya akan jelas bagi pengguna yang lebih mahir?
19. Apakah semuanya akan jelas bagi pengguna pemula?
20. Apakah semuanya logis dan konsisten? Tidak ada lompatan dan jurang?
21. Apakah urutan tindakannya benar? Apakah pengguna dapat mencapai tujuan dengan hanya mengikuti instruksi ini?
22. Sudahkah kita memperhitungkan semua jalur kasus / pengguna?
23. Apakah artikel tersebut sesuai dengan bagian yang dipilih?

Pemeriksaan tata letak

24. Apakah ada lembaran teks yang tidak dapat dibaca? Apakah mungkin untuk mengganti sirkuit?
25. Apakah ada paragraf yang panjang?
26. Apakah ada paragraf yang terlalu pendek?
27. Apakah ada daftar terlalu panjang?
28. Apakah ada daftar yang terlalu rumit untuk persepsi (daftar yang memiliki lebih dari dua atau tiga tingkatan)?
29. Apakah ada cukup gambar?
30. Tidak terlalu banyak gambar? Apakah kita menggambarkan langkah-langkah yang terlalu jelas?
31. Jika ada skema, apakah bisa dimengerti?
32. Tabel tidak sulit untuk persepsi?
33. Apakah keseluruhan halaman terlihat bagus?

Pengeditan Sastra

34. Apakah semuanya dirancang sesuai dengan panduan ini?
35. Apakah gaya dokumentasi sisanya konsisten?
36. Adakah saran yang dapat disederhanakan?
37. Apakah ada istilah rumit yang perlu diklarifikasi?
38. Apakah ada klerikalisme?
39. Apakah ada pengulangan?
40. Apakah tidak ada yang salah dengan pendengaran Anda?

Pengoreksian akhir

41. Apakah ada kesalahan pengetikan, ejaan, atau tanda baca?
42. Apakah tanda hubung, paragraf, dan bagian tidak apa-apa?
43. Apakah semua gambar sudah ditandatangani?
44. Apakah elemen antarmuka diberi nama dengan benar?
45. Apakah ada tautan di mana-mana? Apakah mereka bekerja dan kemana mereka pergi?

Segera setelah publikasi

46. ​​Apakah artikel memiliki bagian yang “ditarik” ke artikel lain? Apakah mereka dihiasi dengan makro sehingga perubahan dalam satu artikel secara otomatis diterapkan ke yang lain?
47. Haruskah artikel ini dirujuk dari bagian lain? Kalau begitu, dari mana?
48. Perlu menambahkan tautan cepat ke artikel ini di produk?
49. Apakah saya harus mengirim tautan ke dukungan, pemasaran, atau departemen lain?
50. Apakah saya harus mengirimkan artikel untuk diterjemahkan?

Daftar ini dapat dicetak dan diletakkan di atas desktop atau digantung di dinding. Atau berubah menjadi daftar periksa. Beberapa pertanyaan dapat dibawa ke dalam proses bisnis. Milik kami, misalnya, diperbaiki dalam proses pengembangan umum di YouTrack. Tugas dokumentasi melewati berbagai tahap dan departemen, tanpa dokumentasi tertulis Anda tidak dapat memberikan fitur untuk dirilis.