Dokumentasi perangkat lunak hanyalah kumpulan artikel, tetapi bahkan itu bisa membuat Anda gila. Pertama Anda mencari instruksi yang tepat untuk waktu yang lama, kemudian Anda memahami teks yang tidak jelas, lakukan seperti yang tertulis, tetapi masalahnya tidak terpecahkan. Anda mencari artikel lain, Anda gugup ... Setelah satu jam Anda meludahi segalanya dan pergi. Inilah cara dokumentasi yang buruk bekerja. Apa yang membuatnya begitu, dan bagaimana cara memperbaikinya - baca di bawah potongan.
Dokumentasi lama kami memiliki banyak kekurangan. Selama hampir satu tahun sekarang kami telah memprosesnya sehingga skenario yang dijelaskan di atas tidak menjadi perhatian pelanggan kami. Lihat bagaimana itu dan bagaimana jadinya .
Masalah 1. Artikel yang tidak dapat dipahami, ditulis dengan buruk
Jika tidak mungkin menemukan dokumentasi, apa gunanya? Tapi tidak ada yang sengaja menulis artikel yang tidak dikenal. Mereka diperoleh ketika penulis tidak memikirkan audiens dan tujuan, menuangkan air dan tidak memeriksa teks untuk kesalahan.
- Hadirin . Sebelum menulis artikel, Anda perlu memikirkan tingkat persiapan pembaca. Adalah logis bahwa dalam artikel untuk pemula Anda tidak boleh melewati langkah-langkah dasar dan meninggalkan istilah teknis tanpa dekripsi, dan dalam artikel tentang fitur langka yang hanya diperlukan untuk para profesional, kunyah makna kata PHP.
- Tujuan Hal lain yang harus Anda pikirkan sebelumnya. Penulis harus menetapkan tujuan yang jelas, menentukan efek yang berguna dari artikel, memutuskan apa yang akan dilakukan pembaca setelah membacanya. Jika ini tidak dilakukan, deskripsi akan diperoleh demi deskripsi.
- Air dan serangga . Banyak informasi dan klerikalisme yang tidak perlu, kesalahan dan kesalahan ketik mengganggu persepsi. Bahkan jika pembaca bukan bangsa tata bahasa, kelalaian dalam teks dapat mendorongnya menjauh.
Pertimbangkan tip di atas, dan artikel akan menjadi lebih jelas - terjamin. Untuk membuatnya lebih baik, ambil
50 pertanyaan kami saat mengerjakan dokumentasi teknis .
Masalah 2. Artikel tidak menjawab semua pertanyaan
Itu buruk ketika dokumentasi tidak mengikuti perkembangan, tidak menjawab pertanyaan nyata, kesalahan di dalamnya belum diperbaiki selama bertahun-tahun. Ini adalah masalah yang tidak begitu banyak penulis sebagai organisasi proses dalam perusahaan.
Dokumentasi tidak mengikuti perkembangan
Fitur ini sudah ada dalam rilis, rencana pemasaran untuk menutupinya, dan ternyata artikel atau terjemahan baru masih belum ada dalam dokumentasi. Karena itu, kami bahkan harus menunda rilis. Anda dapat meminta semua orang untuk menyerahkan tugas kepada penulis teknis tepat waktu, tetapi ini tidak akan berhasil. Jika prosesnya tidak otomatis, situasinya akan berulang.
Kami telah membuat perubahan pada YouTrack. Tugas menulis artikel tentang fitur baru jatuh ke penulis teknis pada saat mereka mulai menguji peluang. Kemudian pemasaran belajar tentang dia untuk mempersiapkan promosi. Pemberitahuan juga datang di messenger perusahaan Mattermost, sehingga tidak mungkin ketinggalan berita dari pengembang.
Dokumentasi tidak mencerminkan permintaan pengguna
Kami dulu bekerja seperti ini: sebuah fitur keluar, kami membicarakannya. Kami menjelaskan cara menyalakannya, mematikan, membuat pengaturan yang baik. Tetapi bagaimana jika klien menggunakan perangkat lunak kami dengan cara yang tidak kami harapkan? Atau apakah dia melakukan kesalahan yang belum kita pikirkan?
Agar dokumentasi selengkap mungkin, kami menyarankan Anda untuk menganalisis permintaan dukungan, pertanyaan di forum tematik, dan pertanyaan di mesin pencari. Topik yang paling populer harus diteruskan ke penulis teknis untuk menambah artikel yang ada atau menulis yang baru.
Dokumentasi tidak diperbaiki
Sulit untuk melakukannya dengan segera, toh akan ada kesalahan. Anda dapat mengandalkan umpan balik dari pelanggan, tetapi mereka tidak mungkin melaporkan setiap kesalahan ketik, tidak akurat, tidak dapat dipahami, atau artikel yang tidak dikenal. Selain pelanggan, karyawan membaca dokumentasi, yang berarti mereka melihat kesalahan yang sama. Itu bisa digunakan! Anda hanya perlu membuat kondisi di mana akan mudah melaporkan masalah.
Kami memiliki grup di portal internal tempat karyawan meninggalkan komentar, saran, dan ide pada dokumentasi. Dukungan membutuhkan artikel tetapi bukan? Apakah tester melihat adanya ketidakakuratan? Mitra mengeluh kepada manajer pengembangan tentang kesalahan? Semua yang ada di grup ini! Penulis teknis segera memperbaiki sesuatu, mentransfer sesuatu ke YouTrack, mengambil sesuatu untuk dipikirkan. Agar topiknya diam, dari waktu ke waktu kami mengingat keberadaan kelompok dan pentingnya umpan balik.
Masalah 3. Anda harus mencari artikel yang tepat untuk waktu yang lama
Artikel yang tidak dapat ditemukan tidak lebih baik dari artikel yang tidak. Moto untuk dokumentasi yang baik harus “Mudah dicari, mudah ditemukan.” Bagaimana cara mencapai ini?
Rampingkan struktur dan tentukan prinsip memilih topik . Strukturnya harus setransparan mungkin sehingga pembaca tidak berpikir "Di mana saya bisa menemukan artikel ini?" Untuk meringkas, ada dua pendekatan: dari antarmuka dan dari tugas.
- Dari antarmuka. Konten menduplikasi bagian panel. Jadi itu dalam dokumentasi sistem ISP lama.
- Dari tugas. Judul artikel dan bagian mencerminkan tugas pengguna; heading hampir selalu berisi kata kerja dan jawaban untuk pertanyaan “how to do”. Sekarang kami pindah ke format ini.
Pendekatan mana pun yang Anda pilih, pastikan bahwa topik tersebut memenuhi kebutuhan pengguna dan dicakup sehingga pengguna secara akurat menyelesaikan pertanyaannya.
Buat pencarian terpusat . Di dunia yang ideal, pencarian harus bekerja bahkan ketika Anda sedih atau salah bahasa. Pencarian kami di Confluence belum bisa menyenangkan ini. Jika Anda memiliki banyak produk, dan dokumentasinya bersifat umum, sesuaikan pencarian dengan halaman tempat pengguna berada. Dalam kasus kami, pencarian utama berfungsi pada semua produk, dan jika Anda sudah berada di bagian tertentu, maka hanya pada artikel di dalamnya.
Tambahkan konten dan remah roti . Ini bagus ketika ada menu dan remah roti pada setiap halaman - jalur pengguna ke halaman saat ini dengan kemampuan untuk kembali ke level apa pun. Dalam dokumentasi sistem ISP lama, Anda harus keluar dari artikel untuk masuk ke konten. Itu merepotkan, jadi kami baru memperbaikinya.
Atur tautan dalam produk . Jika orang-orang datang mendukung dari waktu ke waktu dengan pertanyaan yang sama, masuk akal untuk menambahkan petunjuk dengan solusi ke antarmuka. Jika Anda memiliki data atau pemahaman pada titik mana pengguna dihadapkan dengan masalah, Anda juga dapat memberi tahu dia melalui buletin. Hati-hati dan lepaskan beban dari dukungan.
Di sebelah kanan di jendela pop-up adalah tautan ke artikel tentang pengaturan DNSSEC di bagian manajemen domain ISPmanagerSiapkan referensi silang dalam dokumentasi . Artikel yang terkait harus "ditautkan". Jika artikelnya berurutan, pastikan untuk menambahkan panah maju dan mundur di akhir setiap teks.
Kemungkinan besar, seseorang pertama-tama akan mencari jawaban untuk pertanyaannya, bukan kepada Anda, tetapi ke mesin pencari. Sayang sekali jika tidak ada tautan ke dokumentasi di sana karena alasan teknis. Jadi jaga optimasi mesin pencari.
Masalah 4. Tata letak yang ketinggalan zaman mengganggu persepsi
Selain teks yang buruk, desain dapat merusak dokumentasi. Orang terbiasa membaca materi yang dibuat dengan baik. Blog, jejaring sosial, media - semua konten disajikan tidak hanya cantik, tetapi juga mudah dibaca, enak dipandang. Karena itu, Anda dapat dengan mudah memahami rasa sakit seseorang yang melihat teks seperti pada tangkapan layar di bawah ini.
Ada begitu banyak tangkapan layar dan pilihan dalam artikel ini yang tidak membantu, tetapi hanya mengganggu persepsi (gambar dapat diklik)Tidak ada gunanya membuat longrid dengan banyak efek dari dokumentasi, tetapi Anda perlu mempertimbangkan aturan dasar.
Tata letak Tentukan lebar teks utama, font, ukuran, tajuk dan indentasi. Libatkan seorang desainer, dan untuk menerima pekerjaan atau melakukannya sendiri, bacalah buku Tipografi dan Tata Letak Artyom Gorbunov. Ini hanya menyajikan satu dari pandangan pada tata letak, tetapi itu sudah cukup.
Alokasi . Tentukan apa yang perlu ditekankan dalam teks. Biasanya ini adalah jalur di antarmuka, tombol, sisipan kode, file konfigurasi, blok “Pay attention”. Tetapkan seperti apa pemilihan elemen-elemen ini dan perbaiki dalam jadwal. Perlu diingat bahwa semakin sedikit ekskresi, semakin baik. Ketika ada banyak dari mereka, teks “membuat kebisingan”. Bahkan tanda kutip membuat kebisingan jika digunakan terlalu sering.
Tangkapan layar Atur dengan tim yang membutuhkan tangkapan layar. Jelas tidak perlu menggambarkan setiap langkah. Sejumlah besar tangkapan layar, termasuk tombol individual mengganggu persepsi, tata letak rusak. Tentukan ukuran, serta format pilihan dan keterangan dalam tangkapan layar, perbaiki dalam peraturan. Ingatlah bahwa ilustrasi harus selalu ditulis dan relevan. Sekali lagi, jika produk diperbarui secara berkala, melacak masing-masing akan sulit.
Panjang teks . Hindari artikel yang terlalu panjang. Pisahkan mereka menjadi beberapa bagian, dan jika tidak memungkinkan, tambahkan konten yang terhubung dengan anchor ke bagian atas artikel. Cara mudah untuk membuat artikel lebih pendek secara visual adalah menyembunyikan detail teknis yang dibutuhkan oleh lingkaran sempit pembaca di bawah spoiler.
Format Gabungkan beberapa format dalam artikel: teks, video dan gambar. Ini akan meningkatkan persepsi.
Jangan mencoba menutupi masalah dengan tata letak yang indah. Jujur, kami sendiri berharap bahwa "pembungkus" akan menyimpan dokumentasi yang sudah ketinggalan zaman - itu tidak berhasil. Teks memiliki begitu banyak gangguan visual dan detail yang tidak perlu sehingga peraturan dan desain baru tidak berdaya.
Banyak hal di atas akan ditentukan oleh situs yang Anda gunakan untuk dokumentasi. Bagi kami, misalnya, ini Confluence. Dia juga harus mengotak-atik. Jika tertarik, bacalah kisah pengembang web kami:
Pertemuan untuk basis pengetahuan publik: ubah desain dan atur pemisahan bahasa .
Di mana mulai meningkatkan dan bagaimana bertahan hidup
Jika dokumentasi Anda seluas ISPsystem, dan Anda tidak tahu harus mengambil apa, mulailah dengan masalah yang paling serius. Klien tidak mengerti bagaimana meningkatkan teks, membuat peraturan, dan melatih penulis. Dokumentasi sudah ketinggalan zaman - ambil proses internal. Mulailah dengan artikel paling populer tentang produk yang paling dicari: minta dukungan, lihat analitik situs web dan permintaan mesin pencari.
Katakanlah segera - itu tidak mudah. Dan dengan cepat juga, itu tidak mungkin berhasil. Kecuali jika Anda baru memulai dan melakukan segera. Kami tahu satu hal pasti - itu akan menjadi lebih baik dari waktu ke waktu. Tapi prosesnya tidak akan pernah berakhir :-).