Ang dokumentasyon ng software ay isang hanay lamang ng mga artikulo. Ngunit kahit na sila ay maaaring mabaliw sa iyo. Una, gumugugol ka ng mahabang oras sa paghahanap ng mga kinakailangang tagubilin. Pagkatapos ay naiintindihan mo ang hindi malinaw na teksto. Ginagawa mo ang nakasulat, ngunit hindi nalutas ang problema. Humanap ka ng panibagong artikulo, kinakabahan ka... Makalipas ang isang oras ay sumuko ka sa lahat at umalis. Ganito gumagana ang masamang dokumentasyon. Ano ang ginagawang ganito at kung paano ito ayusin - basahin sa ilalim ng hiwa.
Maraming mga pagkukulang sa aming lumang dokumentasyon. Halos isang taon na namin itong inaayos para hindi maapektuhan ng senaryo na inilarawan sa itaas ang aming mga kliyente. tingnan mo, ΠΈ .
Problema 1: Hindi malinaw, hindi maganda ang pagkakasulat ng mga artikulo
Kung imposibleng maunawaan ang dokumentasyon, ano ang punto nito? Ngunit walang sinuman ang nagsusulat ng hindi maintindihan na mga artikulo sa layunin. Nangyayari ang mga ito kapag hindi iniisip ng may-akda ang tungkol sa madla at layunin, nagbubuhos ng tubig at hindi sinusuri ang teksto para sa mga pagkakamali.
- Ang madla. Bago magsulat ng isang artikulo, kailangan mong isipin ang antas ng paghahanda ng mambabasa. Ito ay lohikal na sa isang artikulo para sa isang baguhan hindi mo dapat laktawan ang mga pangunahing hakbang at iwanan ang mga teknikal na termino nang walang paliwanag, ngunit sa isang artikulo sa isang bihirang tampok na kailangan lamang ng mga propesyonal, dapat mong ipaliwanag ang kahulugan ng salitang PHP.
- Layunin. Isa pang bagay na dapat isipin nang maaga. Ang may-akda ay dapat magtakda ng isang malinaw na layunin, matukoy ang kapaki-pakinabang na epekto ng artikulo, at magpasya kung ano ang gagawin ng mambabasa pagkatapos basahin ito. Kung hindi ito nagawa, magtatapos ka sa paglalarawan para sa kapakanan ng paglalarawan.
- Tubig at mga surot. Maraming hindi kinakailangang impormasyon at burukrasya, ang mga pagkakamali at typo ay nakakasagabal sa pang-unawa. Kahit na ang mambabasa ay hindi isang grammar nazi, ang kawalang-ingat sa teksto ay maaaring mapatay siya.
Isaalang-alang ang mga tip sa itaas, at ang mga artikulo ay magiging mas malinaw - garantisadong. Upang gawin itong mas mahusay, gamitin ang aming .
Problema 2. Hindi sinasagot ng mga artikulo ang lahat ng tanong
Masama kapag ang dokumentasyon ay hindi nakakasabay sa pag-unlad, hindi sumasagot sa mga totoong tanong, at ang mga pagkakamali dito ay hindi naitama sa loob ng maraming taon. Ang mga ito ay mga problema hindi masyadong ng may-akda, ngunit ng organisasyon ng mga proseso sa loob ng kumpanya.
Ang dokumentasyon ay hindi nakakasabay sa pag-unlad
Ang tampok ay inilabas na, plano ng marketing na saklawin ito, at pagkatapos ay lumalabas na ang bagong artikulo o pagsasalin ay wala pa rin sa dokumentasyon. Kinailangan pa naming ipagpaliban ang pagpapalabas dahil dito. Maaari mong hilingin sa lahat na ibigay ang mga gawain sa mga teknikal na manunulat sa oras hangga't gusto mo, ngunit hindi ito gagana. Kung hindi awtomatiko ang proseso, mauulit ang sitwasyon.
Gumawa kami ng mga pagbabago sa YouTrack. Ang gawain ng pagsulat ng isang artikulo tungkol sa isang bagong tampok ay nahuhulog sa teknikal na manunulat sa parehong sandali kapag ang tampok ay nagsimulang masuri. Pagkatapos ay natututo ang marketing tungkol dito upang makapaghanda para sa promosyon. Dumarating din ang mga notification sa Mattermost corporate messenger, kaya imposibleng makaligtaan ang mga balita mula sa mga developer.
Hindi ipinapakita ng dokumentasyon ang mga kahilingan ng user
Nakasanayan na naming magtrabaho ng ganito: may lumabas na feature, pinag-usapan namin. Inilarawan namin kung paano ito i-on, i-off, at gumawa ng magagandang pagsasaayos. Ngunit paano kung ginagamit ng isang kliyente ang aming software sa paraang hindi namin inaasahan? O may mga pagkakamali ba ito na hindi natin naisip?
Upang matiyak na ang dokumentasyon ay kumpleto hangga't maaari, inirerekumenda namin ang pagsusuri ng mga kahilingan sa suporta, mga tanong sa mga pampakay na forum, at mga query sa mga search engine. Ang pinakasikat na mga paksa ay ililipat sa mga teknikal na manunulat upang madagdagan nila ang mga kasalukuyang artikulo o magsulat ng mga bago.
Hindi pinapabuti ang dokumentasyon
Mahirap gawin ito kaagad; magkakaroon pa rin ng mga pagkakamali. Makakaasa ka para sa feedback mula sa mga customer, ngunit malamang na hindi nila iuulat ang bawat typo, hindi tumpak, hindi maintindihan o hindi nahanap na artikulo. Bilang karagdagan sa mga kliyente, binabasa ng mga empleyado ang dokumentasyon, na nangangahulugang nakikita nila ang parehong mga error. Ito ay maaaring gamitin! Kailangan mo lang gumawa ng mga kundisyon kung saan magiging madaling mag-ulat ng problema.
Mayroon kaming grupo sa panloob na portal kung saan ang mga empleyado ay nag-iiwan ng mga komento, mungkahi at ideya sa dokumentasyon. Kailangan ba ng suporta ang isang artikulo, ngunit wala ito? Napansin ba ng tester ang kamalian? Nagreklamo ba ang partner sa mga development manager tungkol sa mga error? Lahat sa grupong ito! Inaayos kaagad ng mga teknikal na manunulat ang ilang bagay, inililipat ang ilang bagay sa YouTrack, at binibigyan ang iba ng ilang oras para pag-isipan. Upang maiwasang mawala ang paksa, paminsan-minsan ay ipinapaalala namin sa iyo ang pagkakaroon ng grupo at ang kahalagahan ng feedback.
Problema 3. Matagal bago mahanap ang tamang artikulo.
Ang isang artikulo na hindi mahanap ay hindi mas mahusay kaysa sa isang artikulo na hindi matagpuan. Ang motto ng magandang dokumentasyon ay dapat na "Madaling hanapin, madaling hanapin." Paano ito makakamit?
Ayusin ang istraktura at tukuyin ang prinsipyo para sa pagpili ng mga paksa. Ang istraktura ay dapat na malinaw hangga't maaari upang ang mambabasa ay hindi mag-isip, "Saan ko mahahanap ang artikulong ito?" Upang ibuod, mayroong dalawang diskarte: mula sa interface at mula sa mga gawain.
- Mula sa interface. Kino-duplicate ng content ang mga seksyon ng panel. Ito ang kaso sa lumang dokumentasyon ng ISPsystem.
- Mula sa mga gawain. Ang mga pamagat ng mga artikulo at mga seksyon ay sumasalamin sa mga gawain ng mga gumagamit; Ang mga pamagat ay halos palaging naglalaman ng mga pandiwa at sagot sa tanong na "paano." Ngayon ay lilipat na kami sa format na ito.
Anuman ang pipiliin mong diskarte, tiyaking may kaugnayan ang paksa sa hinahanap ng mga user at sinasaklaw sa paraang partikular na tumutugon sa tanong ng user.
Mag-set up ng sentralisadong paghahanap. Sa isang perpektong mundo, dapat gumana ang paghahanap kahit na mali ang spell o nagkamali ka sa wika. Ang aming paghahanap sa Confluence sa ngayon ay hindi makapagpapasaya sa amin dito. Kung marami kang produkto at pangkalahatan ang dokumentasyon, iangkop ang paghahanap sa page kung nasaan ang user. Sa aming kaso, ang paghahanap sa pangunahing pahina ay gumagana para sa lahat ng mga produkto, at kung ikaw ay nasa isang partikular na seksyon, pagkatapos ay para lamang sa mga artikulo dito.
Magdagdag ng nilalaman at mga breadcrumb. Mabuti kapag ang bawat page ay may menu at mga breadcrumb - ang landas ng user patungo sa kasalukuyang page na may kakayahang bumalik sa anumang antas. Sa lumang dokumentasyon ng ISPsystem, kailangan mong lumabas sa artikulo upang makarating sa nilalaman. Hindi maginhawa, kaya inayos namin ito sa bago.
Maglagay ng mga link sa produkto. Kung paulit-ulit na suportahan ng mga tao ang parehong tanong, makatuwirang magdagdag ng pahiwatig kasama ang solusyon nito sa interface. Kung mayroon kang data o insight kung kailan nakakaranas ng problema ang isang user, maaari mo ring abisuhan sila gamit ang isang mailing list. Ipakita sa kanila ang pagmamalasakit at alisin ang pasanin sa suporta.
Sa kanan sa pop-up window ay isang link sa isang artikulo tungkol sa pag-set up ng DNSSEC sa seksyon ng pamamahala ng domain ng ISPmanager
Mag-set up ng mga cross-reference sa loob ng dokumentasyon. Ang mga artikulo na may kaugnayan sa isa't isa ay dapat na "naka-link". Kung ang mga artikulo ay sunud-sunod, tiyaking magdagdag ng pasulong at paatras na mga arrow sa dulo ng bawat teksto.
Malamang, ang isang tao ay unang maghahanap ng sagot sa kanyang tanong hindi sa iyo, ngunit sa isang search engine. Sayang lang kung walang link sa documentation doon for technical reasons. Kaya ingatan ang pag-optimize ng search engine.
Problema 4. Ang hindi napapanahong layout ay nakakasagabal sa pang-unawa
Bilang karagdagan sa mga masasamang teksto, ang dokumentasyon ay maaaring masira ng disenyo. Nakasanayan na ng mga tao ang pagbabasa ng mga materyales na mahusay ang pagkakasulat. Mga blog, social network, media - lahat ng nilalaman ay ipinakita hindi lamang maganda, ngunit madaling basahin at kasiya-siya sa mata. Samakatuwid, madali mong maunawaan ang sakit ng isang taong nakakakita ng teksto tulad ng sa screenshot sa ibaba.
Napakaraming mga screenshot at highlight sa artikulong ito na hindi nakakatulong, ngunit nakakasagabal lamang sa pang-unawa (naki-click ang larawan)
Hindi ka dapat gumawa ng mahabang pagbabasa mula sa dokumentasyon na may maraming epekto, ngunit kailangan mong isaalang-alang ang mga pangunahing panuntunan.
Layout. Tukuyin ang lapad ng body text, font, laki, heading, at padding. Mag-hire ng isang taga-disenyo, at upang tanggapin ang trabaho o gawin ito sa iyong sarili, basahin ang aklat ni Artyom Gorbunov na "Typography and Layout." Nagpapakita lamang ito ng isang view ng layout, ngunit ito ay sapat na.
Allotment. Tukuyin kung ano ang nangangailangan ng diin sa teksto. Kadalasan ito ay isang landas sa interface, mga pindutan, mga pagsingit ng code, mga file ng pagsasaayos, mga bloke ng "Pakitandaan". Tukuyin kung ano ang magiging alokasyon ng mga elementong ito at itala ang mga ito sa mga regulasyon. Tandaan na ang mas kaunting discharge, mas mabuti. Kapag marami sila, maingay ang text. Maging ang mga panipi ay lumilikha ng ingay kung madalas itong ginagamit.
Screenshot. Sumang-ayon sa koponan sa kung anong mga kaso ang kailangan ng mga screenshot. Talagang hindi na kailangang ilarawan ang bawat hakbang. Ang isang malaking bilang ng mga screenshot, kasama. hiwalay na mga pindutan, makagambala sa pang-unawa, masira ang layout. Tukuyin ang laki, pati na rin ang format ng mga highlight at lagda sa mga screenshot, at itala ang mga ito sa mga regulasyon. Tandaan na ang mga ilustrasyon ay dapat palaging tumutugma sa kung ano ang nakasulat at may kaugnayan. Muli, kung regular na ina-update ang produkto, magiging mahirap na subaybayan ang lahat.
Haba ng text. Iwasan ang masyadong mahahabang artikulo. Hatiin ang mga ito sa mga bahagi, at kung hindi ito posible, magdagdag ng nilalaman na may mga anchor link sa simula ng artikulo. Ang isang simpleng paraan upang gawing mas maikli ang isang artikulo ay ang pagtatago ng mga teknikal na detalye na kailangan ng isang makitid na bilog ng mga mambabasa sa ilalim ng isang spoiler.
Mga Format. Pagsamahin ang ilang mga format sa iyong mga artikulo: teksto, video at mga larawan. Mapapabuti nito ang pang-unawa.
Huwag subukang pagtakpan ang mga problema sa magandang layout. Sa totoo lang, kami mismo ay umaasa na ang "wrapper" ay magse-save ng hindi napapanahong dokumentasyon - hindi ito gumana. Ang mga teksto ay naglalaman ng napakaraming biswal na ingay at hindi kinakailangang mga detalye na ang mga regulasyon at bagong disenyo ay walang kapangyarihan.
Karamihan sa mga nasa itaas ay matutukoy ng platform na iyong ginagamit para sa dokumentasyon. Halimbawa, mayroon tayong Confluence. Kinailangan ko ring makipagkulitan sa kanya. Kung interesado, basahin ang kuwento ng aming web developer: .
Saan magsisimulang umunlad at kung paano mabuhay
Kung ang iyong dokumentasyon ay kasinglawak ng ISPsystem at hindi mo alam kung saan magsisimula, magsimula sa pinakamalalaking problema. Hindi naiintindihan ng mga kliyente ang dokumento - pagbutihin ang mga teksto, gumawa ng mga regulasyon, sanayin ang mga manunulat. Hindi napapanahon ang dokumentasyon - alagaan ang mga panloob na proseso. Magsimula sa pinakasikat na mga artikulo tungkol sa mga pinakasikat na produkto: humingi ng suporta, tingnan ang analytics ng site at mga query sa mga search engine.
Sabihin na natin kaagad - hindi ito magiging madali. At malamang na hindi rin ito gumana nang mabilis. Maliban na lang kung nagsisimula ka pa lang at gagawin mo na agad ang tama. Ang isang bagay na alam nating sigurado ay ito ay magiging mas mahusay sa paglipas ng panahon. Ngunit ang proseso ay hindi magtatapos :-).
Pinagmulan: www.habr.com