Dokumentasi perangkat lunak hanyalah sekumpulan artikel. Tapi bahkan mereka bisa membuatmu gila. Pertama, Anda menghabiskan waktu lama untuk mencari instruksi yang diperlukan. Kemudian Anda memahami teks yang tidak jelas itu. Anda melakukan seperti yang tertulis, tetapi masalahnya belum terpecahkan. Anda mencari artikel lain, Anda menjadi gugup... Satu jam kemudian Anda menyerah pada segalanya dan pergi. Beginilah cara kerja dokumentasi yang buruk. Apa yang membuatnya seperti ini dan bagaimana cara memperbaikinya - baca di bawah.
Ada banyak kekurangan dalam dokumentasi lama kami. Kami telah mengerjakan ulang selama hampir satu tahun sekarang sehingga skenario yang dijelaskan di atas tidak mempengaruhi klien kami. Lihat, и .
Masalah 1: Artikel yang tidak jelas dan ditulis dengan buruk
Jika dokumentasinya tidak mungkin dipahami, apa gunanya? Tapi tidak ada yang sengaja menulis artikel yang tidak bisa dimengerti. Itu terjadi ketika penulis tidak memikirkan audiens dan tujuannya, menuangkan air dan tidak memeriksa kesalahan teks.
- Hadirin. Sebelum menulis artikel, Anda perlu memikirkan tingkat persiapan pembaca. Wajar jika dalam artikel untuk pemula Anda tidak boleh melewatkan langkah-langkah dasar dan membiarkan istilah teknis tanpa penjelasan, namun dalam artikel tentang fitur langka yang hanya dibutuhkan oleh para profesional, Anda harus menjelaskan arti kata PHP.
- target. Satu hal lagi yang perlu dipikirkan sebelumnya. Penulis harus menetapkan tujuan yang jelas, menentukan manfaat artikel, dan memutuskan apa yang akan dilakukan pembaca setelah membacanya. Jika ini tidak dilakukan, Anda hanya akan mendapatkan deskripsi demi deskripsi.
- Air dan serangga. Banyak informasi dan birokrasi yang tidak perlu, kesalahan dan kesalahan ketik mengganggu persepsi. Sekalipun pembacanya bukan seorang tata bahasa nazi, kecerobohan dalam teks dapat mematikannya.
Simak tips di atas, dan artikelnya akan menjadi lebih jelas – dijamin. Untuk membuatnya lebih baik, gunakan milik kami .
Masalah 2. Artikel tidak menjawab semua pertanyaan
Sangat buruk jika dokumentasi tidak mengikuti perkembangan, tidak menjawab pertanyaan sebenarnya, dan kesalahan di dalamnya tidak diperbaiki selama bertahun-tahun. Ini bukan masalah penulisnya, melainkan masalah pengorganisasian proses dalam perusahaan.
Dokumentasi tidak mengikuti perkembangan
Fitur tersebut sudah dirilis, rencana pemasaran untuk meliputnya, dan ternyata artikel atau terjemahan barunya masih belum ada dalam dokumentasi. Kami bahkan harus menunda perilisannya karena hal ini. Anda dapat meminta semua orang untuk menyerahkan tugas kepada penulis teknis tepat waktu sebanyak yang Anda inginkan, tetapi itu tidak akan berhasil. Jika prosesnya tidak otomatis, situasinya akan terulang kembali.
Kami telah melakukan perubahan pada YouTrack. Tugas menulis artikel tentang fitur baru jatuh ke tangan penulis teknis pada saat yang sama ketika fitur tersebut mulai diuji. Kemudian pemasaran mempelajarinya untuk mempersiapkan promosi. Pemberitahuan juga datang ke utusan perusahaan Mattermost, jadi tidak mungkin ketinggalan berita dari pengembang.
Dokumentasi tidak mencerminkan permintaan pengguna
Kami terbiasa bekerja seperti ini: sebuah fitur keluar, kami membicarakannya. Kami menjelaskan cara menyalakan, mematikannya, dan melakukan penyesuaian halus. Namun bagaimana jika klien menggunakan perangkat lunak kami dengan cara yang tidak kami duga? Atau ada kesalahan yang tidak kita pikirkan?
Untuk memastikan dokumentasi selengkap mungkin, kami menyarankan Anda menganalisis permintaan dukungan, pertanyaan di forum tematik, dan pertanyaan di mesin pencari. Topik yang paling populer akan ditransfer ke penulis teknis sehingga mereka dapat melengkapi artikel yang sudah ada atau menulis artikel baru.
Dokumentasi tidak diperbaiki
Sulit untuk segera melakukannya dengan sempurna; masih akan ada kesalahan. Anda dapat mengharapkan umpan balik dari pelanggan, tetapi kecil kemungkinannya mereka akan melaporkan setiap kesalahan ketik, ketidakakuratan, artikel yang tidak dapat dipahami, atau tidak berdasar. Selain klien, karyawan membaca dokumentasi, yang berarti mereka melihat kesalahan yang sama. Ini bisa digunakan! Anda hanya perlu menciptakan kondisi yang memudahkan untuk melaporkan suatu masalah.
Kami memiliki grup di portal internal tempat karyawan meninggalkan komentar, saran, dan ide tentang dokumentasi. Apakah dukungan memerlukan artikel, tetapi tidak ada? Apakah penguji menyadari ketidakakuratannya? Apakah mitra telah menyampaikan keluhan kepada manajer pengembangan tentang kesalahan? Semua ada di grup ini! Penulis teknis segera memperbaiki beberapa hal, mentransfer beberapa hal ke YouTrack, dan memberikan waktu kepada orang lain untuk memikirkannya. Untuk mencegah topik ini mereda, dari waktu ke waktu kami mengingatkan Anda tentang keberadaan grup dan pentingnya umpan balik.
Masalah 3. Butuh waktu lama untuk menemukan artikel yang tepat.
Artikel yang tidak dapat ditemukan tidak lebih baik dari artikel yang tidak dapat ditemukan. Motto dokumentasi yang baik adalah “Mudah dicari, mudah ditemukan.” Bagaimana cara mencapainya?
Mengatur struktur dan menentukan prinsip pemilihan topik. Strukturnya harus setransparan mungkin sehingga pembaca tidak berpikir, “Di mana saya bisa menemukan artikel ini?” Ringkasnya, ada dua pendekatan: dari antarmuka dan dari tugas.
- Dari antarmuka. Kontennya menduplikasi bagian panel. Hal ini terjadi pada dokumentasi sistem ISP yang lama.
- Dari tugas. Judul artikel dan bagian mencerminkan tugas pengguna; Judul hampir selalu mengandung kata kerja dan jawaban atas pertanyaan “bagaimana caranya”. Sekarang kita beralih ke format ini.
Pendekatan apa pun yang Anda pilih, pastikan topiknya relevan dengan apa yang dicari pengguna dan dibahas dengan cara yang secara spesifik menjawab pertanyaan pengguna.
Siapkan pencarian terpusat. Idealnya, penelusuran harus tetap berfungsi meskipun Anda salah mengeja atau membuat kesalahan dalam bahasa. Pencarian kami di Confluence sejauh ini tidak dapat menyenangkan kami dengan hal ini. Jika Anda memiliki banyak produk dan dokumentasinya bersifat umum, sesuaikan pencarian dengan halaman tempat pengguna berada. Dalam kasus kami, pencarian di halaman utama berfungsi untuk semua produk, dan jika Anda sudah berada di bagian tertentu, maka hanya untuk artikel di dalamnya.
Tambahkan konten dan remah roti. Ada baiknya bila setiap halaman memiliki menu dan remah roti - jalur pengguna ke halaman saat ini dengan kemampuan untuk kembali ke tingkat mana pun. Dalam dokumentasi sistem ISP lama, Anda harus keluar dari artikel untuk mendapatkan kontennya. Itu tidak nyaman, jadi kami memperbaikinya dengan yang baru.
Tempatkan tautan di produk. Jika orang datang untuk mendukung berulang kali dengan pertanyaan yang sama, masuk akal untuk menambahkan petunjuk dengan solusinya ke antarmuka. Jika Anda memiliki data atau wawasan ketika pengguna mengalami masalah, Anda juga dapat memberi tahu mereka melalui milis. Tunjukkan pada mereka kepedulian dan hilangkan beban dukungan.
Di sebelah kanan jendela pop-up terdapat link ke artikel tentang pengaturan DNSSEC di bagian manajemen domain ISPmanager
Siapkan referensi silang dalam dokumentasi. Artikel-artikel yang berkaitan satu sama lain hendaknya “dihubungkan”. Jika artikelnya berurutan, pastikan untuk menambahkan panah maju dan mundur di akhir setiap teks.
Kemungkinan besar, seseorang pertama-tama akan mencari jawaban atas pertanyaannya bukan kepada Anda, tetapi ke mesin pencari. Sangat disayangkan jika tidak ada link dokumentasi disana karena alasan teknis. Jadi jagalah optimasi mesin pencari.
Masalah 4. Tata letak yang ketinggalan jaman mengganggu persepsi
Selain teks yang buruk, dokumentasi juga dapat rusak karena desain. Orang terbiasa membaca materi yang ditulis dengan baik. Blog, jejaring sosial, media - semua konten yang disajikan tidak hanya indah, tetapi juga mudah dibaca dan enak dipandang. Oleh karena itu, Anda dapat dengan mudah memahami kepedihan seseorang yang melihat teks seperti pada gambar di bawah.
Banyak sekali screenshot dan highlight di artikel ini yang tidak membantu, melainkan hanya mengganggu persepsi (gambar bisa diklik)
Anda tidak boleh membuat bacaan panjang dari dokumentasi dengan banyak efek, tetapi Anda perlu mempertimbangkan aturan dasarnya.
Tata Letak. Tentukan lebar isi teks, font, ukuran, judul, dan padding. Pekerjakan seorang desainer, dan untuk menerima pekerjaan tersebut atau mengerjakannya sendiri, bacalah buku Artyom Gorbunov “Typography and Layout.” Ini hanya menyajikan satu tampilan tata letak, tetapi sudah cukup.
Discharge. Tentukan apa yang memerlukan penekanan dalam teks. Biasanya ini adalah jalur di antarmuka, tombol, sisipan kode, file konfigurasi, blok "Harap diperhatikan". Tentukan alokasi unsur-unsur tersebut dan catat dalam peraturan. Ingatlah bahwa semakin sedikit debitnya, semakin baik. Kalau banyak, teksnya berisik. Bahkan tanda kutip pun menimbulkan kebisingan jika digunakan terlalu sering.
Layar. Setuju dengan tim dalam hal apa tangkapan layar diperlukan. Jelas tidak perlu mengilustrasikan setiap langkah. Sejumlah besar tangkapan layar, termasuk. tombol terpisah, mengganggu persepsi, merusak tata letak. Tentukan ukuran, serta format highlight dan tanda tangan pada tangkapan layar, dan catat dalam peraturan. Ingatlah bahwa ilustrasi harus selalu sesuai dengan apa yang tertulis dan relevan. Sekali lagi, jika produk diperbarui secara berkala, akan sulit untuk melacak semua orang.
Panjang teks. Hindari artikel yang terlalu panjang. Bagi menjadi beberapa bagian, dan jika tidak memungkinkan, tambahkan konten dengan tautan jangkar ke awal artikel. Cara sederhana untuk membuat artikel lebih pendek secara visual adalah dengan menyembunyikan detail teknis yang dibutuhkan oleh kalangan pembaca yang sempit di bawah spoiler.
Форматы. Gabungkan beberapa format dalam artikel Anda: teks, video, dan gambar. Hal ini akan meningkatkan persepsi.
Jangan mencoba menutupi masalah dengan tata letak yang indah. Sejujurnya, kami sendiri berharap "pembungkus" akan menyimpan dokumentasi yang sudah ketinggalan zaman - ternyata tidak berhasil. Teks-teks tersebut mengandung begitu banyak gangguan visual dan detail yang tidak perlu sehingga peraturan dan desain baru tidak berdaya.
Sebagian besar hal di atas akan ditentukan oleh platform yang Anda gunakan untuk dokumentasi. Misalnya, kami memiliki Confluence. Aku juga harus bermain-main dengannya. Jika tertarik, baca kisah pengembang web kami: .
Di mana harus mulai berkembang dan bagaimana cara bertahan
Jika dokumentasi Anda sama luasnya dengan sistem ISP dan Anda tidak tahu harus mulai dari mana, mulailah dengan masalah terbesar. Klien tidak memahami dokumen - memperbaiki teks, membuat peraturan, melatih penulis. Dokumentasi sudah kedaluwarsa - urus proses internal. Mulailah dengan artikel terpopuler tentang produk terpopuler: tanyakan dukungan, lihat analisis situs, dan kueri di mesin pencari.
Katakanlah segera - itu tidak akan mudah. Dan kemungkinan besar hal ini juga tidak akan berhasil dengan cepat. Kecuali Anda baru memulai dan segera melakukan hal yang benar. Satu hal yang kami tahu pasti adalah bahwa hal ini akan menjadi lebih baik seiring berjalannya waktu. Namun prosesnya tidak akan pernah berakhir :-).
Sumber: www.habr.com