Dokumentasi perisian hanyalah satu set artikel. Tetapi mereka juga boleh membuat anda gila. Pertama, anda menghabiskan masa yang lama mencari arahan yang diperlukan. Kemudian anda memahami teks yang tidak jelas. Anda lakukan seperti yang tertulis, tetapi masalahnya tidak diselesaikan. Anda mencari artikel lain, anda menjadi gementar... Sejam kemudian anda menyerah pada segala-galanya dan pergi. Beginilah cara dokumentasi yang buruk berfungsi. Apa yang menjadikannya seperti ini dan cara membetulkannya - baca di bawah potongan.
Terdapat banyak kekurangan dalam dokumentasi lama kami. Kami telah mengolahnya semula selama hampir setahun sekarang supaya senario yang diterangkan di atas tidak menjejaskan pelanggan kami. lihat, ΠΈ .
Masalah 1: Artikel yang tidak jelas dan ditulis dengan buruk
Jika dokumentasi itu mustahil untuk difahami, apakah gunanya? Tetapi tiada siapa yang menulis artikel yang tidak dapat difahami dengan sengaja. Ia berlaku apabila pengarang tidak memikirkan penonton dan tujuan, menuangkan air dan tidak menyemak teks untuk kesilapan.
- Penonton. Sebelum menulis artikel, anda perlu memikirkan tahap persediaan pembaca. Adalah logik bahawa dalam artikel untuk pemula anda tidak boleh melangkau langkah asas dan meninggalkan istilah teknikal tanpa penjelasan, tetapi dalam artikel mengenai ciri jarang yang hanya diperlukan oleh profesional, anda harus menerangkan maksud perkataan PHP.
- Matlamat. Satu lagi perkara yang perlu difikirkan terlebih dahulu. Pengarang mesti menetapkan matlamat yang jelas, menentukan kesan berguna artikel itu, dan memutuskan apa yang pembaca akan lakukan selepas membacanya. Jika ini tidak dilakukan, anda akan mendapat penerangan demi penerangan.
- Air dan pepijat. Terdapat banyak maklumat yang tidak perlu dan birokrasi, kesilapan dan kesilapan menaip mengganggu persepsi. Walaupun pembaca bukan nazi tatabahasa, kecuaian dalam teks boleh mematikannya.
Pertimbangkan petua di atas, dan artikel akan menjadi lebih jelas - dijamin. Untuk menjadikannya lebih baik, gunakan kami .
Masalah 2. Artikel tidak menjawab semua soalan
Adalah buruk apabila dokumentasi tidak mengikuti perkembangan, tidak menjawab soalan sebenar, dan ralat di dalamnya tidak diperbetulkan selama bertahun-tahun. Ini bukan masalah pengarang, tetapi masalah organisasi proses dalam syarikat.
Dokumentasi tidak mengikuti perkembangan
Ciri ini sudah pun dikeluarkan, pemasaran merancang untuk menutupnya, dan kemudian ternyata artikel atau terjemahan baharu itu masih tiada dalam dokumentasi. Kami juga terpaksa menangguhkan pelepasan kerana ini. Anda boleh meminta semua orang menyerahkan tugas kepada penulis teknikal tepat pada masa yang anda mahu, tetapi ia tidak akan berjaya. Jika proses itu tidak automatik, keadaan akan berulang.
Kami telah membuat perubahan pada YouTrack. Tugas menulis artikel tentang ciri baharu jatuh kepada penulis teknikal pada masa yang sama apabila ciri itu mula diuji. Kemudian pemasaran mempelajarinya untuk persediaan untuk promosi. Pemberitahuan juga dihantar kepada utusan korporat Mattermost, jadi mustahil untuk terlepas berita daripada pembangun.
Dokumentasi tidak menggambarkan permintaan pengguna
Kami sudah biasa bekerja seperti ini: satu ciri keluar, kami bercakap mengenainya. Kami menerangkan cara menghidupkannya, mematikannya dan membuat pelarasan yang baik. Tetapi bagaimana jika pelanggan menggunakan perisian kami dengan cara yang tidak kami jangkakan? Atau adakah ia mempunyai kesilapan yang tidak kita fikirkan?
Untuk memastikan bahawa dokumentasi adalah selengkap mungkin, kami mengesyorkan anda menganalisis permintaan sokongan, soalan pada forum tematik dan pertanyaan dalam enjin carian. Topik yang paling popular akan dipindahkan kepada penulis teknikal supaya mereka boleh menambah artikel sedia ada atau menulis yang baharu.
Dokumentasi tidak diperbaiki
Sukar untuk melakukannya dengan segera; masih akan ada kesilapan. Anda boleh mengharapkan maklum balas daripada pelanggan, tetapi tidak mungkin mereka akan melaporkan setiap kesilapan kesilapan, ketidaktepatan, tidak dapat difahami atau artikel yang tidak ditemui. Selain pelanggan, pekerja membaca dokumentasi, yang bermaksud mereka melihat ralat yang sama. Ini boleh digunakan! Anda hanya perlu mencipta keadaan di mana ia akan menjadi mudah untuk melaporkan masalah.
Kami mempunyai kumpulan di portal dalaman di mana pekerja meninggalkan komen, cadangan dan idea tentang dokumentasi. Adakah sokongan memerlukan artikel, tetapi ia tidak wujud? Adakah penguji menyedari ketidaktepatan itu? Adakah rakan kongsi telah mengadu kepada pengurus pembangunan tentang kesilapan? Semua dalam kumpulan ini! Penulis teknikal membetulkan beberapa perkara dengan segera, memindahkan beberapa perkara ke YouTrack dan memberi orang lain sedikit masa untuk berfikir. Untuk mengelakkan topik daripada mati, dari semasa ke semasa kami mengingatkan anda tentang kewujudan kumpulan dan kepentingan maklum balas.
Masalah 3. Ia mengambil masa yang lama untuk mencari artikel yang sesuai.
Artikel yang tidak dapat ditemui tidak lebih baik daripada artikel yang tidak dapat ditemui. Moto dokumentasi yang baik hendaklah "Mudah dicari, mudah dicari." Bagaimana untuk mencapai ini?
Susun struktur dan tentukan prinsip untuk memilih topik. Strukturnya hendaklah setelus mungkin supaya pembaca tidak berfikir, "Di manakah saya boleh mencari artikel ini?" Untuk meringkaskan, terdapat dua pendekatan: dari antara muka dan dari tugas.
- Daripada antara muka. Kandungan menduplikasi bahagian panel. Ini adalah kes dalam dokumentasi sistem ISP lama.
- Daripada tugasan. Tajuk artikel dan bahagian mencerminkan tugas pengguna; Tajuk hampir selalu mengandungi kata kerja dan jawapan kepada soalan "bagaimana". Sekarang kita beralih ke format ini.
Walau apa pun pendekatan yang anda pilih, pastikan topik itu berkaitan dengan perkara yang dicari oleh pengguna dan diliputi dengan cara yang menangani soalan pengguna secara khusus.
Sediakan carian terpusat. Dalam dunia yang ideal, carian harus berfungsi walaupun anda tersilap mengeja atau membuat kesilapan dengan bahasa tersebut. Pencarian kami di Confluence setakat ini tidak dapat menggembirakan kami dengan perkara ini. Jika anda mempunyai banyak produk dan dokumentasinya adalah umum, sesuaikan carian dengan halaman yang digunakan pengguna. Dalam kes kami, carian di halaman utama berfungsi untuk semua produk, dan jika anda sudah berada di bahagian tertentu, maka hanya untuk artikel di dalamnya.
Tambah kandungan dan serbuk roti. Ia bagus apabila setiap halaman mempunyai menu dan serbuk roti - laluan pengguna ke halaman semasa dengan keupayaan untuk kembali ke mana-mana peringkat. Dalam dokumentasi sistem ISP lama, anda perlu keluar dari artikel untuk mendapatkan kandungan. Ia menyusahkan, jadi kami membetulkannya dalam yang baharu.
Letakkan pautan dalam produk. Jika orang datang untuk menyokong berulang kali dengan soalan yang sama, masuk akal untuk menambah pembayang dengan penyelesaiannya pada antara muka. Jika anda mempunyai data atau cerapan tentang apabila pengguna mengalami masalah, anda juga boleh memberitahu mereka dengan senarai mel. Tunjukkan keprihatinan mereka dan lepaskan beban daripada sokongan.
Di sebelah kanan dalam tetingkap timbul ialah pautan ke artikel tentang menyediakan DNSSEC dalam bahagian pengurusan domain ISPmanager
Sediakan rujukan silang dalam dokumentasi. Artikel yang berkaitan antara satu sama lain harus "dipautkan". Jika artikel adalah berurutan, pastikan anda menambah anak panah ke hadapan dan ke belakang pada akhir setiap teks.
Kemungkinan besar, seseorang mula-mula akan mencari jawapan kepada soalannya bukan kepada anda, tetapi kepada enjin carian. Sungguh memalukan jika tiada pautan ke dokumentasi di sana atas sebab teknikal. Jadi jaga pengoptimuman enjin carian.
Masalah 4. Susun atur yang lapuk mengganggu persepsi
Selain teks yang buruk, dokumentasi boleh dirosakkan oleh reka bentuk. Orang ramai terbiasa membaca bahan yang ditulis dengan baik. Blog, rangkaian sosial, media - semua kandungan dipersembahkan bukan sahaja cantik, tetapi juga mudah dibaca dan menyenangkan mata. Oleh itu, anda boleh memahami dengan mudah kesakitan seseorang yang melihat teks seperti dalam tangkapan skrin di bawah.
Terdapat begitu banyak tangkapan skrin dan sorotan dalam artikel ini yang tidak membantu, tetapi hanya mengganggu persepsi (gambar boleh diklik)
Anda tidak sepatutnya membuat bacaan panjang daripada dokumentasi dengan banyak kesan, tetapi anda perlu mengambil kira peraturan asas.
Susun atur. Tentukan lebar teks badan, fon, saiz, tajuk dan padding. Upah seorang pereka, dan untuk menerima kerja atau melakukannya sendiri, baca buku Artyom Gorbunov "Tipografi dan Reka Letak." Ia membentangkan hanya satu pandangan susun atur, tetapi ia cukup mencukupi.
Peruntukan. Tentukan perkara yang memerlukan penekanan dalam teks. Biasanya ini adalah laluan dalam antara muka, butang, sisipan kod, fail konfigurasi, blok "Sila ambil perhatian". Tentukan apakah peruntukan unsur-unsur ini dan catatkannya dalam peraturan. Perlu diingat bahawa lebih sedikit pelepasan, lebih baik. Apabila terdapat banyak daripada mereka, teks menjadi bising. Malah tanda petikan menimbulkan bunyi jika ia digunakan terlalu kerap.
Screenshot. Bersetuju dengan pasukan dalam keadaan apa tangkapan skrin diperlukan. Pastinya tidak perlu menggambarkan setiap langkah. Sebilangan besar tangkapan skrin, termasuk. butang berasingan, mengganggu persepsi, merosakkan susun atur. Tentukan saiz, serta format sorotan dan tandatangan pada tangkapan skrin, dan rekodkannya dalam peraturan. Ingat bahawa ilustrasi hendaklah sentiasa sepadan dengan apa yang ditulis dan relevan. Sekali lagi, jika produk dikemas kini dengan kerap, sukar untuk menjejaki semua orang.
Panjang teks. Elakkan artikel yang terlalu panjang. Pecahkannya kepada beberapa bahagian, dan jika ini tidak mungkin, tambahkan kandungan dengan pautan utama pada permulaan artikel. Cara mudah untuk menjadikan artikel secara visual lebih pendek adalah dengan menyembunyikan butiran teknikal yang diperlukan oleh kalangan pembaca yang sempit di bawah spoiler.
Format. Gabungkan beberapa format dalam artikel anda: teks, video dan imej. Ini akan meningkatkan persepsi.
Jangan cuba menutup masalah dengan susun atur yang cantik. Secara jujur, kami sendiri berharap bahawa "pembungkus" akan menyimpan dokumentasi yang sudah lapuk - ia tidak berjaya. Teks tersebut mengandungi begitu banyak bunyi visual dan butiran yang tidak perlu sehingga peraturan dan reka bentuk baharu tidak berkuasa.
Kebanyakan perkara di atas akan ditentukan oleh platform yang anda gunakan untuk dokumentasi. Sebagai contoh, kita mempunyai Confluence. Saya terpaksa bermain-main dengan dia juga. Jika berminat, baca kisah pembangun web kami: .
Di mana untuk mula bertambah baik dan bagaimana untuk terus hidup
Jika dokumentasi anda seluas sistem ISP dan anda tidak tahu di mana hendak bermula, mulakan dengan masalah terbesar. Pelanggan tidak memahami dokumen - memperbaiki teks, membuat peraturan, melatih penulis. Dokumentasi sudah lapuk - jaga proses dalaman. Mulakan dengan artikel paling popular tentang produk paling popular: minta sokongan, lihat analitis tapak dan pertanyaan dalam enjin carian.
Katakan segera - ia tidak akan mudah. Dan ia tidak mungkin berfungsi dengan cepat sama ada. Melainkan anda baru bermula dan melakukan perkara yang betul dengan segera. Satu perkara yang kita pasti adalah bahawa ia akan menjadi lebih baik dari masa ke masa. Tetapi proses itu tidak akan pernah berakhir :-).
Sumber: www.habr.com