Dokumentasi piranti lunak mung sakumpulan artikel. Nanging malah padha bisa nggawe sampeyan edan. Pisanan, sampeyan ngenteni suwene nggoleki instruksi sing dibutuhake. Banjur sampeyan ngerti teks sing ora jelas. Sampeyan nindakake kaya sing ditulis, nanging masalah ora ditanggulangi. Sampeyan nggoleki artikel liyane, sampeyan bakal gugup ... Sejam mengko sampeyan nyerah kabeh lan ninggalake. Iki minangka dokumentasi sing ala. Apa sing nggawe kaya iki lan carane ndandani - maca ing ngisor potong.
Ana akeh kekurangan ing dokumentasi lawas kita. Kita wis nggarap maneh meh setaun saiki supaya skenario sing kasebut ing ndhuwur ora mengaruhi klien kita. Delengen, ΠΈ .
Masalah 1: Artikel sing ora jelas, ditulis kanthi apik
Yen dokumentasi ora bisa dingerteni, apa gunane? Nanging ora ana sing nulis artikel sing ora dingerteni kanthi sengaja. Iki kedadeyan nalika penulis ora mikir babagan pamirsa lan tujuane, pour banyu lan ora mriksa teks kanggo kesalahan.
- Para pamirsa. Sadurunge nulis artikel, sampeyan kudu mikir babagan tingkat persiapan pamaca. Iku logis yen ing artikel kanggo pamula sampeyan ora kudu ngliwati langkah-langkah dhasar lan ninggalake istilah teknis tanpa panjelasan, nanging ing artikel babagan fitur langka sing mung perlu profesional, sampeyan kudu nerangake makna tembung PHP.
- Tujuane. Siji liyane sing kudu dipikirake sadurunge. Penulis kudu nemtokake tujuan sing jelas, nemtokake efek sing migunani saka artikel kasebut, lan mutusake apa sing bakal ditindakake maca sawise maca. Yen iki ora rampung, sampeyan bakal mungkasi karo katrangan kanggo katrangan.
- Banyu lan kewan omo. Ana akeh informasi sing ora perlu lan birokrasi, kesalahan lan kesalahan ketik ngganggu persepsi. Sanajan sing maca dudu nazi grammar, kecerobohan ing teks bisa mateni dheweke.
Coba tips ing ndhuwur, lan artikel bakal dadi luwih jelas - dijamin. Kanggo nggawe luwih apik, gunakake kita .
Masalah 2. Artikel ora njawab kabeh pitakonan
Iku ala nalika dokumentasi ora terus karo pembangunan, ora njawab pitakonan nyata, lan kasalahan ing iku ora didandani kanggo taun. Iki minangka masalah ora akeh penulis, nanging babagan organisasi proses ing perusahaan.
Dokumentasi ora ngetutake perkembangan
Fitur kasebut wis diluncurake, rencana marketing kanggo nutupi, banjur dadi artikel utawa terjemahan anyar isih ora ana ing dokumentasi. Kita malah kudu nundha rilis amarga iki. Sampeyan bisa njaluk kabeh wong nyerahake tugas menyang panulis teknis ing wektu sing dikarepake, nanging ora bakal bisa. Yen proses ora otomatis, kahanan bakal mbaleni dhewe.
Kita wis nggawe owah-owahan ing YouTrack. Tugas nulis artikel babagan fitur anyar tiba ing panulis teknis ing wektu sing padha nalika fitur kasebut wiwit diuji. Banjur marketing sinau babagan iki kanggo nyiapake promosi. Kabar uga teka ing utusan perusahaan Mattermost, saengga ora bisa ketinggalan kabar saka pangembang.
Dokumentasi ora nggambarake panjalukan pangguna
Kita wis biasa kerja kaya iki: ana fitur sing metu, kita ngomong babagan iki. Kita nerangake carane nguripake, mateni, lan nggawe pangaturan apik. Nanging kepiye yen klien nggunakake piranti lunak kanthi cara sing ora dikarepake? Utawa ana kesalahan sing ora kita pikirake?
Kanggo mesthekake yen dokumentasi lengkap sabisa, disaranake nganalisa panjalukan dhukungan, pitakonan ing forum tematik, lan pitakon ing mesin telusur. Topik sing paling populer bakal ditransfer menyang panulis teknis supaya bisa nambah artikel sing wis ana utawa nulis sing anyar.
Dokumentasi ora didandani
Pancen angel ditindakake kanthi cepet; isih ana kesalahan. Sampeyan bisa ngarep-arep umpan balik saka pelanggan, nanging ora mungkin dheweke bakal nglaporake saben tulisan sing salah, ora akurat, ora bisa dingerteni utawa ora ditemokake. Saliyane klien, karyawan maca dokumentasi, tegese padha ndeleng kesalahan sing padha. Iki bisa digunakake! Sampeyan mung kudu nggawe kahanan sing bakal gampang nglaporake masalah.
Kita duwe grup ing portal internal ing ngendi karyawan ninggalake komentar, saran lan gagasan babagan dokumentasi. Apa dhukungan mbutuhake artikel, nanging ora ana? Apa tester ngelingi ora akurat? Apa partner ngeluh menyang manajer pangembangan babagan kesalahan? Kabeh ing grup iki! Penulis teknis langsung ndandani sawetara perkara, ngirim sawetara perkara menyang YouTrack, lan menehi sawetara wektu kanggo mikir. Kanggo nyegah topik saka mati, saka wektu kanggo wektu kita ngelingake sampeyan anane grup lan pentinge umpan balik.
Masalah 3. Butuh wektu suwe kanggo nemokake artikel sing bener.
Artikel sing ora bisa ditemokake ora luwih apik tinimbang artikel sing ora ditemokake. Motto dokumentasi sing apik kudu "Gampang digoleki, gampang ditemokake." Kepiye carane entuk iki?
Ngatur struktur lan nemtokake prinsip kanggo milih topik. Struktur kasebut kudu transparan supaya sing maca ora mikir, "Ing endi aku bisa nemokake artikel iki?" Kanggo ngringkes, ana rong pendekatan: saka antarmuka lan saka tugas.
- Saka antarmuka. Isi duplikat bagean panel. Iki kedadeyan ing dokumentasi ISPsystem lawas.
- Saka tugas. Judhul artikel lan bagean nggambarake tugas pangguna; Judhul meh tansah ngemot kriya lan jawaban kanggo pitakonan "carane". Saiki kita pindhah menyang format iki.
Apa wae pendekatan sing sampeyan pilih, priksa manawa topik kasebut cocog karo apa sing digoleki pangguna lan dijangkepi kanthi cara khusus kanggo ngatasi pitakonan pangguna.
Nggawe telusuran terpusat. Ing donya sing becik, telusuran kudu bisa digunakake sanajan sampeyan salah nulis utawa nggawe kesalahan nganggo basa kasebut. Panelusuran kita ing Confluence nganti saiki ora bisa nyenengake kita. Yen sampeyan duwe akeh produk lan dokumentasi umum, atur telusuran menyang kaca sing digunakake pangguna. Ing kasus kita, telusuran ing kaca utama bisa digunakake kanggo kabeh produk, lan yen sampeyan wis ana ing bagean tartamtu, mung kanggo artikel kasebut.
Tambah isi lan breadcrumbs. Iku apik nalika saben kaca duwe menu lan breadcrumbs - path pangguna menyang kaca saiki kanthi kemampuan kanggo bali menyang tingkat sembarang. Ing dokumentasi ISPsystem lawas, sampeyan kudu metu saka artikel kanggo entuk konten. Iku ora trep, supaya kita ndandani ing anyar.
Selehake pranala ing produk. Yen wong teka kanggo ndhukung maneh lan maneh karo pitakonan padha, iku ndadekake pangertèn kanggo nambah Petunjuk karo solusi kanggo antarmuka. Yen sampeyan duwe data utawa wawasan nalika pangguna ngalami masalah, sampeyan uga bisa menehi kabar karo mailing list. Tampilake keprihatinan lan njupuk beban saka dhukungan.
Ing sisih tengen jendela pop-up ana link menyang artikel babagan nyetel DNSSEC ing bagean manajemen domain ISPmanager.
Nggawe referensi silang ing dokumentasi. Artikel sing ana hubungane karo siji liyane kudu "disambung". Yen artikel kasebut runtut, manawa sampeyan nambahake panah maju lan mundur ing pungkasan saben teks.
Paling kamungkinan, wong pisanan bakal golek jawaban kanggo pitakonan ora kanggo sampeyan, nanging kanggo search engine. Iku isin yen ora ana pranala menyang dokumentasi ing kana amarga alasan teknis. Dadi ngurus optimasi mesin telusuran.
Masalah 4. tata letak outdated ngganggu pemahaman
Saliyane teks sing ala, dokumentasi bisa dirusak kanthi desain. Wong wis biasa maca bahan sing ditulis kanthi apik. Blog, jaringan sosial, media - kabeh isi diwenehi ora mung ayu, nanging uga gampang diwaca lan nyenengake kanggo mripat. Mulane, sampeyan bisa kanthi gampang ngerti rasa lara wong sing ndeleng teks kaya gambar ing ngisor iki.
Ana akeh gambar lan sorotan ing artikel iki sing ora mbantu, nanging mung ngganggu persepsi (gambar bisa diklik)
Sampeyan ora kudu nggawe longread saka dokumentasi karo Bunch saka efek, nanging sampeyan kudu njupuk menyang akun aturan dhasar.
Tata letak. Nemtokake jembar teks awak, font, ukuran, judhul, lan padding. Nyewa desainer, lan nampa karya utawa nindakake dhewe, maca buku Artyom Gorbunov "Tipografi lan Tata Letak". Iku presents mung siji tampilan saka tata letak, nanging cukup cukup.
Alokasi. Nemtokake apa sing mbutuhake penekanan ing teks. Biasane iki minangka dalan ing antarmuka, tombol, sisipan kode, file konfigurasi, pamblokiran "Mangga dicathet". Temtokake apa alokasi unsur kasebut lan cathet ing peraturan kasebut. Elinga yen kurang discharge, luwih apik. Nalika ana akeh, teks kasebut rame. Malah tandha petik nggawe gangguan yen asring digunakake.
Screenshot. Setuju karo tim ing kasus apa gambar sing dibutuhake. Ana mesthi ora perlu kanggo ilustrasi saben langkah. A nomer akeh gambar, kalebu. tombol kapisah, ngganggu pemahaman, ngrusak tata letak. Temtokake ukuran, uga format sorotan lan teken ing gambar, lan rekam ing peraturan. Elinga yen ilustrasi kudu cocog karo apa sing ditulis lan relevan. Maneh, yen produk kasebut dianyari kanthi rutin, bakal angel nglacak kabeh wong.
Dawane teks. Ngindhari artikel sing dawa banget. Pecah dadi bagean, lan yen ora bisa, tambahake konten kanthi tautan jangkar menyang wiwitan artikel. Cara prasaja kanggo nggawe artikel luwih cendhek kanthi visual yaiku ndhelikake rincian teknis sing dibutuhake dening pembaca sing sempit ing sangisore spoiler.
Format. Gabungke sawetara format ing artikel sampeyan: teks, video lan gambar. Iki bakal nambah pemahaman.
Aja nyoba kanggo nutupi masalah karo tata letak ayu. Jujur, kita dhewe ngarep-arep manawa "pembungkus" bakal nyimpen dokumentasi sing wis lawas - ora bisa ditindakake. Teks kasebut ngemot akeh gangguan visual lan rincian sing ora perlu, saengga peraturan lan desain anyar ora ana daya.
Kathah ing ndhuwur bakal ditemtokake dening platform sing digunakake kanggo dokumentasi. Contone, kita duwe Confluence. Aku uga kudu tinker karo dheweke. Yen kasengsem, waca crita pangembang web kita: .
Where kanggo miwiti nambah lan carane urip
Yen dokumentasi sampeyan jembar kaya ISPsystem lan sampeyan ora ngerti kudu miwiti saka ngendi, mula kanthi masalah sing paling gedhe. Klien ora ngerti dokumen kasebut - nambah teks, nggawe peraturan, nglatih panulis. Dokumentasi wis kadaluwarsa - ngurus proses internal. Mulai karo artikel sing paling populer babagan produk sing paling populer: njaluk dhukungan, deleng analytics situs lan pitakon ing mesin telusur.
Ayo langsung ngomong - ora bakal gampang. Lan ora bisa uga kanthi cepet. Kajaba yen sampeyan lagi miwiti lan nindakake perkara sing bener. Siji bab sing kita ngerti manawa bakal dadi luwih apik saka wektu. Nanging proses ora bakal mungkasi :-).
Source: www.habr.com