Dokumentazzjoni tas-softwer hija biss sett ta 'artikoli. Imma anke huma jistgħu jsuquk miġnun. L-ewwel, inti tqatta 'żmien twil tfittex l-istruzzjonijiet meħtieġa. Imbagħad tifhem it-test oskur. Int tagħmel kif miktub, iżda l-problema mhix solvuta. Tfittex artiklu ieħor, tispiċċa nervuż... Siegħa wara ċċedi minn kollox u titlaq. Hekk taħdem id-dokumentazzjoni ħażina. X'jagħmilha bħal din u kif tiffissa - aqra taħt il-qatgħa.
Kien hemm ħafna nuqqasijiet fid-dokumentazzjoni l-antika tagħna. Ilna naħdmuha mill-ġdid għal kważi sena issa biex ix-xenarju deskritt hawn fuq ma jaffettwax lill-klijenti tagħna. Ara, и .
Problema 1: Artikli mhux ċari, miktubin ħażin
Jekk id-dokumentazzjoni hija impossibbli li tinftiehem, x'inhu l-punt tagħha? Imma ħadd ma jikteb artikli li ma jinftiehmux apposta. Jiġru meta l-awtur ma jaħsibx dwar l-udjenza u l-iskop, iferra l-ilma u ma jiċċekkjax it-test għal żbalji.
- Sala tal-Lectures. Qabel ma tikteb artiklu, trid taħseb dwar il-livell ta 'preparazzjoni tal-qarrej. Huwa loġiku li f'artiklu għal Bidu m'għandekx taqbeż il-passi bażiċi u tħalli termini tekniċi mingħajr spjegazzjoni, iżda f'artiklu dwar karatteristika rari li għandhom bżonn il-professjonisti biss, għandek tispjega t-tifsira tal-kelma PHP.
- Goal. Ħaġa oħra biex taħseb minn qabel. L-awtur għandu jistabbilixxi mira ċara, jiddetermina l-effett utli tal-artiklu, u jiddeċiedi x'se jagħmel il-qarrej wara li jaqrah. Jekk dan ma jsirx, tispiċċa b'deskrizzjoni għall-fini tad-deskrizzjoni.
- Ilma u bugs. Hemm ħafna informazzjoni bla bżonn u burokrazija, żbalji u typos jinterferixxu mal-perċezzjoni. Anke jekk il-qarrej ma jkunx nazi grammatika, traskuraġni fit-test jista 'jitfih.
Ikkunsidra l-pariri hawn fuq, u l-artikoli se jsiru aktar ċari - garantiti. Biex tagħmilha aħjar, uża tagħna .
Problema 2. L-artikoli ma jwieġbux il-mistoqsijiet kollha
Huwa ħażin meta d-dokumentazzjoni ma tlaħħaqx mal-iżvilupp, ma twieġebx mistoqsijiet reali, u l-iżbalji fiha ma jiġux ikkoreġuti għal snin. Dawn huma problemi mhux tant tal-awtur, iżda tal-organizzazzjoni tal-proċessi fi ħdan il-kumpanija.
Id-dokumentazzjoni ma tlaħħaqx mal-iżvilupp
Il-karatteristika hija diġà fir-rilaxx, il-kummerċjalizzazzjoni tippjana li tkopriha, u mbagħad jirriżulta li l-artikolu jew it-traduzzjoni l-ġdid għadu mhux fid-dokumentazzjoni. Saħansitra kellna nipposponu r-rilaxx minħabba dan. Tista 'titlob lil kulħadd biex jgħaddi l-kompiti lil kittieba tekniċi fil-ħin kemm trid, iżda mhux se taħdem. Jekk il-proċess ma jkunx awtomatizzat, is-sitwazzjoni tirrepeti ruħha.
Għamilna bidliet għal YouTrack. Il-kompitu li tikteb artiklu dwar karatteristika ġdida taqa 'f'idejn il-kittieb tekniku fl-istess mument meta l-karatteristika tibda tiġi ttestjata. Imbagħad il-kummerċjalizzazzjoni titgħallem dwarha sabiex tipprepara għall-promozzjoni. In-notifiki jidħlu wkoll fil-messaġġier korporattiv ta 'Mattermost, għalhekk huwa sempliċement impossibbli li titlef aħbarijiet mill-iżviluppaturi.
Id-dokumentazzjoni ma tirriflettix it-talbiet tal-utenti
Aħna mdorrijin naħdmu hekk: ħarġet karatteristika, tkellimna dwarha. Aħna ddeskrivejna kif tixgħelha, titfiha, u tagħmel aġġustamenti fini. Imma x'jiġri jekk klijent juża s-software tagħna b'mod li ma stennejniex? Jew għandu żbalji li aħna ma ħsibniex dwarhom?
Biex niżguraw li d-dokumentazzjoni tkun kompluta kemm jista’ jkun, nirrakkomandaw li tanalizza talbiet ta’ appoġġ, mistoqsijiet dwar forums tematiċi, u mistoqsijiet fil-magni tat-tiftix. L-aktar suġġetti popolari se jiġu trasferiti lil kittieba tekniċi sabiex ikunu jistgħu jissupplimentaw artikli eżistenti jew jiktbu oħrajn ġodda.
Id-dokumentazzjoni mhix qed titjieb
Huwa diffiċli li tagħmel dan perfettament mill-ewwel xorta jkun hemm żbalji. Tista 'tama għal feedback mill-klijenti, iżda huwa improbabbli li jirrappurtaw kull typo, ineżattezza, artikolu inkomprensibbli jew mhux misjub. Minbarra l-klijenti, l-impjegati jaqraw id-dokumentazzjoni, li jfisser li jaraw l-istess żbalji. Dan jista 'jintuża! Għandek bżonn biss li toħloq kundizzjonijiet li fihom ikun faċli li tirrapporta problema.
Għandna grupp fuq il-portal intern fejn l-impjegati jħallu kummenti, suġġerimenti u ideat dwar id-dokumentazzjoni. L-appoġġ jeħtieġ artiklu, iżda ma jeżistix? It-tester innota l-ineżattezza? Is-sieħeb ilmenta mal-maniġers tal-iżvilupp dwar żbalji? Kollha f'dan il-grupp! Il-kittieba tekniċi jiffissaw xi affarijiet mill-ewwel, jittrasferixxu xi affarijiet fuq YouTrack, u jagħtu ftit ħin lil oħrajn biex jaħsbu dwarhom. Biex tevita li s-suġġett jitmut, minn żmien għal żmien infakkruk fl-eżistenza tal-grupp u l-importanza tar-rispons.
Problema 3. Huwa jieħu ħafna żmien biex issib l-artiklu t-tajjeb.
Artiklu li ma jistax jinstab mhu aħjar minn artiklu li ma jistax jinstab. Il-motto ta' dokumentazzjoni tajba għandu jkun "Faċli biex tfittex, faċli biex issibha." Kif tikseb dan?
Organizza l-istruttura u tiddetermina l-prinċipju għall-għażla tas-suġġetti. L-istruttura għandha tkun trasparenti kemm jista’ jkun sabiex il-qarrej ma jaħsibx, “Fejn nista’ nsib dan l-artiklu?” Fil-qosor, hemm żewġ approċċi: mill-interface u mill-kompiti.
- Mill-interface. Il-kontenut jidduplika s-sezzjonijiet tal-panel. Dan kien il-każ fid-dokumentazzjoni tal-ISPsystem l-antika.
- Mill-kompiti. It-titli tal-artikoli u t-taqsimiet jirriflettu l-kompiti tal-utenti; It-titli kważi dejjem fihom verbi u tweġibiet għall-mistoqsija "kif". Issa qed nimxu għal dan il-format.
Tkun xi tkun l-approċċ li tagħżel, kun żgur li s-suġġett huwa rilevanti għal dak li qed ifittxu l-utenti u huwa kopert b'mod li jindirizza speċifikament il-mistoqsija tal-utent.
Stabbilixxi tfittxija ċentralizzata. F'dinja ideali, it-tfittxija għandha taħdem anke meta tikteb ħażin jew tagħmel żball bil-lingwa. It-tfittxija tagħna f'Confluence s'issa ma tistax togħġobna b'dan. Jekk għandek ħafna prodotti u d-dokumentazzjoni hija ġenerali, fassal it-tfittxija għall-paġna li jkun qiegħed fuqha l-utent. Fil-każ tagħna, it-tfittxija fuq il-paġna ewlenija taħdem għall-prodotti kollha, u jekk diġà tinsab f'sezzjoni speċifika, allura biss għall-artikoli fiha.
Żid il-kontenut u l-frak tal-ħobż. Huwa tajjeb meta kull paġna jkollha menu u frak tal-ħobż - it-triq tal-utent għall-paġna attwali bil-kapaċità li terġa 'lura għal kwalunkwe livell. Fid-dokumentazzjoni tal-ISPsystem l-antika, kellek toħroġ mill-artiklu biex tasal għall-kontenut. Kien inkonvenjenti, għalhekk issewwiha f'dik il-ġdida.
Poġġi links fil-prodott. Jekk in-nies jiġu biex jappoġġjaw aktar u aktar mill-ġdid bl-istess mistoqsija, jagħmel sens li żżid ħjiel bis-soluzzjoni tagħha għall-interface. Jekk għandek dejta jew għarfien dwar meta utent ikun qed jesperjenza problema, tista' wkoll tinnotifikahom b'lista tal-posta. Urihom tħassib u neħħi l-piż mill-appoġġ.
Fuq il-lemin fit-tieqa pop-up hemm link għal artiklu dwar it-twaqqif ta’ DNSSEC fit-taqsima tal-ġestjoni tad-dominju ta’ ISPmanager
Stabbilixxi referenzi inkroċjati fid-dokumentazzjoni. L-artikoli li huma relatati ma' xulxin għandhom ikunu "konnessi". Jekk l-artikoli huma sekwenzjali, kun żgur li żżid vleġeġ 'il quddiem u lura fl-aħħar ta' kull test.
Ħafna probabbli, persuna l-ewwel tmur tfittex tweġiba għall-mistoqsija tagħha mhux lilek, iżda lil magna tat-tiftix. Hija tal-mistħija jekk ma jkunx hemm links għad-dokumentazzjoni hemmhekk għal raġunijiet tekniċi. Allura ħu ħsieb l-ottimizzazzjoni tal-magna tat-tiftix.
Problema 4. It-tqassim skadut jinterferixxi mal-perċezzjoni
Minbarra testi ħżiena, id-dokumentazzjoni tista 'tiġi mħassra bid-disinn. In-nies huma mdorrijin jaqraw materjal miktub tajjeb. Blogs, netwerks soċjali, midja - il-kontenut kollu huwa ppreżentat mhux biss sabiħ, iżda wkoll faċli biex jinqara u pjaċir għall-għajn. Għalhekk, tista 'faċilment tifhem l-uġigħ ta' persuna li tara test bħal fil-screenshot hawn taħt.
Hemm tant screenshots u punti ewlenin f'dan l-artikolu li ma jgħinux, iżda jinterferixxu biss mal-perċezzjoni (l-istampa tista' tikklikkja)
M'għandekx tagħmel qari fit-tul mid-dokumentazzjoni b'mazz ta 'effetti, iżda trid tieħu kont tar-regoli bażiċi.
Tqassim. Iddetermina l-wisa' tat-test tal-ġisem, it-tipa, id-daqs, l-intestaturi u l-ikkuttunar. Kiri disinjatur, u biex taċċetta x-xogħol jew tagħmel it yourself, aqra l-ktieb ta 'Artyom Gorbunov "Tipografija u Layout." Jippreżenta veduta waħda biss tat-tqassim, iżda huwa pjuttost biżżejjed.
Allokazzjonijiet. Iddetermina dak li jeħtieġ enfasi fit-test. Tipikament din hija mogħdija fl-interface, buttuni, inserzjonijiet tal-kodiċi, fajls ta 'konfigurazzjoni, blokki "Jekk jogħġbok innota". Iddetermina x'se jkunu l-allokazzjonijiet ta' dawn l-elementi u rreġistrahom fir-regolamenti. Żomm f'moħħok li l-inqas ħruġ, l-aħjar. Meta jkun hemm ħafna minnhom, it-test ikun storbjuż. Anke l-virgoletti joħolqu storbju jekk jintużaw spiss wisq.
Screenshots. Aqbel mat-tim f'liema każijiet huma meħtieġa screenshots. Żgur m'hemmx bżonn li jintwerew kull pass. Numru kbir ta 'screenshots, inkl. buttuni separati, jinterferixxu mal-perċezzjoni, iħassru t-tqassim. Iddetermina d-daqs, kif ukoll il-format tal-punti ewlenin u l-firem fuq screenshots, u rreġistrahom fir-regolamenti. Ftakar li l-illustrazzjonijiet għandhom dejjem jikkorrispondu għal dak li hu miktub u jkunu rilevanti. Għal darb'oħra, jekk il-prodott jiġi aġġornat regolarment, ikun diffiċli li żżomm kont ta 'kulħadd.
Tul tat-test. Evita artikoli twal iżżejjed. Aqsamhom f'partijiet, u jekk dan ma jkunx possibbli, żid kontenut b'links ta 'ankra fil-bidu tal-artikolu. Mod sempliċi biex tagħmel artiklu viżwalment iqsar huwa li taħbi d-dettalji tekniċi meħtieġa minn ċirku dejjaq ta 'qarrejja taħt spoiler.
Formati. Għaqqad diversi formati fl-artikoli tiegħek: test, vidjo u stampi. Dan se jtejjeb il-perċezzjoni.
Tippruvax tgħatti l-problemi b'tqassim sabiħ. Onestament, aħna stess nittamaw li l-"wrapper" se jsalva d-dokumentazzjoni skaduta - ma ħadmitx. It-testi tant kien fihom ħsejjes viżwali u dettalji bla bżonn li r-regolamenti u d-disinn il-ġdid ma setgħux.
Ħafna minn dan t'hawn fuq se jiġi determinat mill-pjattaforma li tuża għad-dokumentazzjoni. Per eżempju, għandna Confluence. Jiena kelli ndaqq miegħu wkoll. Jekk interessat, aqra l-istorja tal-iżviluppatur tal-web tagħna: .
Fejn tibda ttejjeb u kif tgħix
Jekk id-dokumentazzjoni tiegħek hija vasta daqs dik tal-ISPsystem u ma tafx minn fejn tibda, ibda bl-akbar problemi. Il-klijenti ma jifhmux id-dokument - itejbu t-testi, jagħmlu regolamenti, iħarrġu kittieba. Id-dokumentazzjoni hija skaduta - ħu ħsieb il-proċessi interni. Ibda bl-artikoli l-aktar popolari dwar il-prodotti l-aktar popolari: staqsi appoġġ, ħares lejn l-analiżi tas-sit u mistoqsijiet fil-magni tat-tiftix.
Ejja ngħidu mill-ewwel - mhux se jkun faċli. U mhux probabbli li taħdem malajr lanqas. Sakemm ma tkunx qed tibda u tagħmel it-tajjeb mill-ewwel. Ħaġa waħda li nafu żgur hija li se titjieb maż-żmien. Imma l-proċess ma jintemm qatt :-).
Sors: www.habr.com
