Dokuméntasi parangkat lunak ngan ukur sakumpulan tulisan. Tapi malah maranéhna bisa ngajalankeun anjeun gélo. Kahiji, anjeun méakkeun lila pilari parentah diperlukeun. Teras anjeun ngartos téks anu teu jelas. Anjeun ngalakukeun sakumaha ditulis, tapi masalahna teu direngsekeun. Anjeun néangan artikel séjén, anjeun meunang saraf ... Sajam engké anjeun nyerah dina sagalana jeung ninggalkeun. Ieu kumaha dokuméntasi goréng jalan. Naon ngajadikeun eta kawas kieu jeung kumaha carana ngalereskeun eta - baca handapeun cut.
Aya seueur kakurangan dina dokuméntasi lami urang. Kami parantos ngerjakeun deui ampir sataun ayeuna supados skenario anu dijelaskeun di luhur henteu mangaruhan klien kami. Neuteup, и .
Masalah 1: Tulisan anu teu jelas, kurang ditulis
Lamun dokuméntasi teu mungkin ngartos, naon gunana? Tapi teu aya anu ngahaja nyerat tulisan anu teu kaharti. Éta lumangsung nalika panulis teu mikir ngeunaan panongton jeung tujuan, tuang cai jeung teu pariksa téks pikeun kasalahan.
- Para hadirin. Sateuacan nyerat tulisan, anjeun kedah mikirkeun tingkat persiapan pamaca. Logis yén dina tulisan pikeun pamula anjeun henteu kedah ngalangkungan léngkah-léngkah dasar sareng ngantepkeun istilah téknis tanpa katerangan, tapi dina tulisan ngeunaan fitur anu jarang anu ngan ukur para profesional peryogi, anjeun kedah ngajelaskeun harti kecap PHP.
- tujuan. Hiji deui anu kedah dipikirkeun sateuacanna. Nu nulis kudu nangtukeun tujuan nu jelas, nangtukeun pangaruh mangpaat tina artikel, jeung mutuskeun naon nu maca sanggeus maca eta. Lamun ieu teu dipigawé, anjeun bakal mungkas nepi ka pedaran demi pedaran.
- Cai jeung bug. Aya seueur inpormasi anu teu perlu sareng birokrasi, kasalahan sareng typos ngaganggu persepsi. Sanaos pamaca sanés grammar Nazi, kalemahan dina téks tiasa mareuman anjeunna.
Pertimbangkeun tip di luhur, sareng tulisan bakal langkung jelas - dijamin. Pikeun ngajantenkeun langkung saé, paké kami .
Masalah 2. Artikel teu ngajawab sakabéh patarosan
Éta goréng nalika dokuméntasi henteu nuturkeun pamekaran, henteu ngajawab patarosan anu nyata, sareng kasalahan dina éta henteu dilereskeun mangtaun-taun. Ieu mangrupikeun masalah sanés panulis, tapi ngeunaan organisasi prosés dina perusahaan.
Dokuméntasi henteu nuturkeun pangwangunan
Fiturna parantos dileupaskeun, pamasaran ngarencanakeun pikeun nutupan éta, teras tétéla yén tulisan atanapi tarjamahan énggal masih teu aya dina dokuméntasi. Kami malah kedah nunda pelepasan kusabab ieu. Anjeun tiasa naroskeun sadayana pikeun nyerahkeun tugas ka panulis téknis dina waktos anu dipikahoyong, tapi éta moal jalan. Upami prosésna henteu otomatis, kaayaan bakal malikan deui.
Kami parantos ngarobih kana YouTrack. Tugas nulis artikel ngeunaan fitur anyar digolongkeun kana panulis teknis dina waktos anu sareng nalika fitur mimiti diuji. Teras pamasaran diajar ngeunaan éta pikeun nyiapkeun promosi. Bewara ogé sumping ka utusan perusahaan Mattermost, janten teu mungkin kantun warta ti pamekar.
Dokuméntasi henteu ngagambarkeun paménta pangguna
Kami biasa damel sapertos kieu: fitur kaluar, kami nyarioskeun éta. Kami ngajelaskeun kumaha carana ngaktipkeun, mareuman, sareng ngadamel panyesuaian anu saé. Tapi kumaha upami klien nganggo parangkat lunak kami dina cara anu teu disangka-sangka? Atanapi éta ngagaduhan kasalahan anu teu urang pikirkeun?
Pikeun mastikeun yén dokuméntasi lengkep sabisa, kami nyarankeun nganalisis pamundut dukungan, patarosan dina forum tematik, sareng patarosan dina mesin pencari. Topik anu pang populerna bakal dialihkeun ka panulis téknis supados aranjeunna tiasa nambihan tulisan anu tos aya atanapi nyerat anu énggal.
Dokuméntasi henteu dironjatkeun
Hésé pikeun ngalakukeunana sacara langsung; masih bakal aya kasalahan. Anjeun tiasa ngaharepkeun eupan balik ti para nasabah, tapi teu mungkin yen aranjeunna bakal ngalaporkeun unggal typo, inaccuracy, teu kaharti atawa unfound artikel. Salian klien, karyawan maca dokuméntasi, nu hartina maranéhna ningali kasalahan anu sarua. Ieu bisa dipaké! Anjeun ngan ukur kedah nyiptakeun kaayaan dimana éta bakal gampang ngalaporkeun masalah.
Simkuring boga grup dina portal internal dimana karyawan ninggalkeun komentar, saran jeung gagasan dina dokuméntasi. Naha dukungan peryogi artikel, tapi henteu aya? Naha panguji perhatikeun henteu akurat? Naha pasangan ngawadul ka manajer pangembangan ngeunaan kasalahan? Sadayana di grup ieu! Panulis teknis ngalereskeun sababaraha hal langsung, mindahkeun sababaraha hal ka YouTrack, sareng masihan waktos ka batur pikeun mikir. Pikeun nyegah topik ti dying handap, ti jaman ka jaman kami ngingetan ngeunaan ayana grup jeung pentingna eupan balik.
Masalah 3. Butuh waktu lila pikeun manggihan artikel katuhu.
Artikel nu teu bisa kapanggih teu leuwih hade tinimbang artikel nu teu bisa kapanggih. Motto dokuméntasi anu saé kedahna "Gampang milarian, gampang mendakan." Kumaha carana ngahontal ieu?
Atur struktur jeung nangtukeun prinsip pikeun milih topik. Strukturna kedah transparan-gancang supados pamaca henteu mikir, "Dimana kuring mendakan tulisan ieu?" Pikeun nyimpulkeun, aya dua pendekatan: tina antarmuka sareng tina tugas.
- Tina panganteur. Eusi duplikat bagian panel. Ieu kasus dina dokuméntasi ISPsystem heubeul.
- Tina tugas. Judul artikel sareng bagian ngagambarkeun tugas para pangguna; Judul ampir sok ngandung kecap gawe jeung jawaban kana patarosan "kumaha carana". Ayeuna urang ngalih ka format ieu.
Naon waé pendekatan anu anjeun pilih, pastikeun topikna relevan sareng anu dipilarian ku pangguna sareng katutupan ku cara anu sacara khusus ngémutan patarosan pangguna.
Nyetél pilarian terpusat. Dina dunya idéal, pilarian kedah dianggo sanajan anjeun salah ngeja atawa nyieun kasalahan dina basa. Pilarian kami di Confluence dugi ka ayeuna teu tiasa nyenangkeun kami. Upami anjeun gaduh seueur produk sareng dokuméntasi umumna, saluyukeun panéangan kana halaman anu dianggo ku pangguna. Dina hal urang, pilarian dina kaca utama lumaku pikeun sakabéh produk, sarta lamun geus aya dina bagian husus, mangka ngan pikeun artikel di dinya.
Tambahkeun eusi na breadcrumbs. Éta saé nalika unggal halaman ngagaduhan ménu sareng breadcrumbs - jalur pangguna ka halaman ayeuna kalayan kamampuan uih deui ka tingkat mana waé. Dina dokuméntasi ISPsystem anu lami, anjeun kedah kaluar tina tulisan pikeun ngahontal kontén. Ieu teu merenah, jadi urang ngalereskeun eta dina nu anyar.
Pasang tautan dina produk. Lamun jalma datang ka ngarojong leuwih sarta leuwih deui jeung sual sarua, ngajadikeun rasa pikeun nambahkeun hint jeung solusi na pikeun panganteur dina. Upami anjeun gaduh data atanapi wawasan nalika pangguna ngalaman masalah, anjeun ogé tiasa ngabéjaan aranjeunna kalayan milis. Tunjukkeun aranjeunna prihatin sareng cabut beban tina dukungan.
Di katuhu dina jandela pop-up aya tumbu ka artikel ngeunaan nyetel DNSSEC dina bagian manajemén domain ISPmanager.
Nyetél rujukan silang dina dokuméntasi. Artikel-artikel anu aya patalina jeung nu séjénna kudu "dihubungkeun". Upami artikelna berurutan, pastikeun pikeun nambihan panah maju sareng mundur dina tungtung unggal téks.
Paling dipikaresep, hiji jalma bakal mimiti néangan jawaban kana patarosan na teu ka anjeun, tapi ka mesin pencari. Éra upami teu aya tautan kana dokuméntasi di dinya kusabab alesan téknis. Janten jaga optimasi mesin pencari.
Masalah 4. perenah luntur interferes kalawan persepsi
Salian téks goréng, dokuméntasi bisa manja ku desain. Jalma-jalma biasa maca bahan-bahan anu ditulisna alus. Blog, jaringan sosial, média - sagala eusi dibere teu ukur geulis, tapi ogé gampang dibaca tur pleasing kana panon. Ku alatan éta, anjeun bisa kalayan gampang ngarti nyeri hiji jalma anu ningali téks kawas dina screenshot handap.
Aya seueur potret layar sareng sorotan dina tulisan ieu anu henteu ngabantosan, tapi ngan ukur ngaganggu persépsi (gambar tiasa diklik)
Anjeun teu kedah maca panjang tina dokuméntasi kalayan seueur épék, tapi anjeun kedah tumut kana aturan dasar.
Tata perenah. Nangtukeun lebar téks awak, font, ukuran, judul, sareng padding. Nyewa desainer, sareng nampi padamelan atanapi ngalakukeunana nyalira, baca buku Artyom Gorbunov "Tipografi sareng Tata Letak". Ieu presents ngan hiji tempoan perenah nu, tapi geus cukup cukup.
Alokasi. Nangtukeun naon anu peryogi tekenan dina téks. Biasana ieu jalur dina panganteur, tombol, sisipan kode, file konfigurasi, "Punten dicatet" blok. Nangtukeun naon alokasi unsur-unsur ieu sareng rekam dina peraturan. Terus di pikiran nu kirang ngurangan, nu hadé. Nalika aya seueur, téksna ribut. Malah tanda petik nyieun noise lamun aranjeunna dipaké teuing mindeng.
Potret layar. Satuju sareng tim dina kasus naon screenshot anu diperyogikeun. Aya pasti teu kudu ngagambarkeun unggal hambalan. Sajumlah ageung Potret layar, kalebet. tombol misah, ngaganggu persepsi, ngaruksak perenah. Nangtukeun ukuranana, kitu ogé format sorotan sareng tanda tangan dina Potret layar, sareng rekam dina peraturan. Émut yén ilustrasi kedah salawasna cocog sareng anu diserat sareng relevan. Sakali deui, upami produkna diropéa sacara teratur, éta bakal sesah ngalacak sadayana.
Panjang téks. Hindarkeun tulisan anu panjang teuing. Megatkeun kana bagian, sarta lamun ieu teu mungkin, tambahkeun eusi kalawan tumbu jangkar ka awal artikel. Cara anu saderhana pikeun ngajantenkeun tulisan sacara visual langkung pondok nyaéta nyumputkeun detail téknis anu diperyogikeun ku bunderan sempit pamiarsa handapeun spoiler.
Format. Gabungkeun sababaraha format dina artikel anjeun: téks, video sareng gambar. Ieu bakal ningkatkeun persepsi.
Entong nyobian nutupan masalah kalayan perenah anu saé. Jujur, urang sorangan ngarepkeun yén "bungkus" bakal ngahémat dokuméntasi anu luntur - éta henteu hasil. Naskah-naskah ngandung seueur bising visual sareng detil anu teu dipikabutuh sahingga peraturan sareng desain énggal teu aya kakuatanana.
Seueur anu di luhur bakal ditangtukeun ku platform anu anjeun anggo pikeun dokuméntasi. Salaku conto, urang gaduh Confluence. Kuring kungsi tinker jeung manéhna ogé. Upami kabetot, baca carita pamekar wéb kami: .
Dimana ngamimitian ningkatkeun sareng kumaha salamet
Upami dokuméntasi anjeun ageung sapertos ISPsystem sareng anjeun henteu terang dimana ngamimitian, mimitian ku masalah anu paling ageung. Klién henteu ngartos dokumén - ningkatkeun téks, ngadamel peraturan, ngalatih panulis. Dokuméntasi parantos lami - urus prosés internal. Mimitian ku tulisan anu pang populerna ngeunaan produk anu pang populerna: naroskeun dukungan, tingali analytics situs sareng patarosan dina mesin pencari.
Sebutkeun langsung - éta moal gampang. Sareng éta ogé henteu tiasa dianggo gancang. Kacuali anjeun ngan ukur ngamimitian sareng ngalakukeun hal anu leres langsung. Hiji hal anu urang terang pasti nyaéta yén éta bakal langkung saé dina waktosna. Tapi prosésna moal aya tungtungna :-).
sumber: www.habr.com