Softwarearen dokumentazioa artikulu multzo bat besterik ez da. Baina haiek ere erotu dezakete. Lehenik eta behin, denbora luzea ematen duzu beharrezko argibideak bilatzen. Orduan ulertzen duzu testu iluna. Idatzitakoa egiten duzu, baina arazoa ez da konpondu. Beste artikulu bat bilatzen duzu, urduri jartzen zara... Ordubete geroago dena utzi eta alde egiten duzu. Horrela funtzionatzen du dokumentazio txarra. Zer egiten duen horrela eta nola konpondu - irakurri ebakiaren azpian.
Gure dokumentazio zaharrean gabezia asko zeuden. Ia urtebete daramagu berriro lantzen, goian azaldutako eszenatokiak gure bezeroei eragin ez diezaien. Begira, ΠΈ .
1. arazoa: Artikulu argiak eta gaizki idatziak
Dokumentazioa ulertzea ezinezkoa bada, zertarako balio du? Baina inork ez du nahita idazten artikulu ulertezinak. Egileak ikuslegoari eta xedeari buruz pentsatzen ez duenean, ura botatzen du eta testuan akatsik ikusten ez duenean gertatzen dira.
- Ikusleak. Artikulu bat idatzi aurretik, irakurlearen prestaketa mailari buruz pentsatu behar duzu. Logikoa da hasiberrientzako artikulu batean oinarrizko urratsak ez saltatu eta termino teknikoak azalpenik gabe utzi behar izatea, baina profesionalek bakarrik behar duten ezaugarri arraro bati buruzko artikulu batean PHP hitzaren esanahia azaldu beharko zenuke.
- Helburua. Aldez aurretik pentsatu beharreko beste gauza bat. Egileak helburu argi bat ezarri behar du, artikuluaren eragin erabilgarria zehaztu eta irakurri ondoren irakurleak zer egingo duen erabaki. Hau egiten ez bada, deskribapenarekin amaituko duzu deskribapenaren mesedetan.
- Ura eta zomorroak. Alferrikako informazio eta burokrazia asko dago, akatsek eta akatsek pertzepzioa oztopatzen dute. Nahiz eta irakurlea gramatika nazia ez izan, testuan arduragabekeriak itzali dezake.
Kontuan hartu goiko aholkuak, eta artikuluak argiagoak izango dira - bermatuta. Are hobea izateko, erabili gure .
2. arazoa. Artikuluek ez dituzte galdera guztiei erantzuten
Txarra da dokumentazioak garapenarekin jarraitzen ez duenean, benetako galderei erantzuten ez dienean eta bertan dauden akatsak urtetan zuzentzen ez direnean. Hauek ez dira horrenbeste egilearen arazoak, enpresa barruko prozesuen antolaketarena baizik.
Dokumentazioak ez du garapenarekin jarraitzen
Ezaugarri hori kaleratzean dago dagoeneko, marketin-ak estaltzeko asmoa du, eta orduan gertatzen da artikulu edo itzulpen berria oraindik ez dagoela dokumentazioan. Askapena ere atzeratu behar izan genuen horregatik. Denei eska diezaiekezu zereginak idazle teknikoei nahi adina garaiz entregatzeko, baina ez du funtzionatuko. Prozesua automatizatzen ez bada, egoera errepikatuko da.
Aldaketak egin ditugu YouTrack-en. Ezaugarri berri bati buruzko artikulu bat idazteko zeregina idazle teknikoaren esku dago funtzioa probatzen hasten den une berean. Ondoren, marketinak horri buruz ikasten du sustapenerako prestatzeko. Jakinarazpenak Mattermost mezulari korporatiboari ere heltzen zaizkio, beraz, ezinezkoa da garatzaileen albisteak galtzea.
Dokumentazioak ez ditu erabiltzaileen eskaerak islatzen
Ohituta gaude horrela lan egitera: ezaugarri bat atera zen, horretaz hitz egin genuen. Piztu, itzali eta doikuntza finak nola egin deskribatu genuen. Baina zer gertatzen da bezero batek gure softwarea espero ez genuen moduan erabiltzen badu? Edo ba al ditu pentsatu ez ditugun akatsak?
Dokumentazioa ahalik eta osatuena izan dadin, laguntza eskaerak, gaikako foroetako galderak eta bilatzaileetako kontsultak aztertzea gomendatzen dugu. Gai ezagunenak idazle teknikoei helaraziko zaizkie, lehendik dauden artikuluak osatu edo berriak idatzi ditzaten.
Dokumentazioa ez da hobetzen ari
Zaila da primeran egitea; akatsak egongo dira oraindik. Bezeroen iritzia espero dezakezu, baina zaila da idazketa, zehaztasun, ulertezin edo aurkitu gabeko artikulu guztien berri emango dutenik. Bezeroez gain, langileek dokumentazioa irakurtzen dute, hau da, akats berdinak ikusten dituzte. Hau erabil daiteke! Arazo baten berri ematea erraza izango den baldintzak sortu besterik ez duzu behar.
Barne atarian talde bat dugu, non langileek dokumentazioari buruzko iruzkinak, iradokizunak eta ideiak uzten dituzten. Laguntzak artikulu bat behar al du, baina ez da existitzen? Probatzaileak zehazgabetasuna nabaritu al zuen? Bazkidea kexatu al da garapeneko arduradunekin akatsengatik? Denak talde honetan! Idazle teknikoek gauza batzuk berehala konpontzen dituzte, gauza batzuk YouTrack-era transferitzen dituzte eta besteei pentsatzeko denbora pixka bat ematen diete. Gaia hil ez dadin, noizean behin taldearen existentzia eta feedbackaren garrantzia gogorarazten dizuegu.
3. arazoa. Denbora luzea behar da artikulu egokia aurkitzeko.
Aurkitu ezin den artikulua ez da aurkitu ezin den artikulu bat baino. Dokumentazio onaren leloa "Bilatzeko erraza, aurkitzea erraza" izan behar da. Nola lortu hori?
Egitura antolatzea eta gaiak aukeratzeko printzipioa zehaztea. Egiturak ahalik eta gardenena izan behar du, irakurleak ez dezan pentsatu: "Non aurki dezaket artikulu hau?" Laburbilduz, bi ikuspegi daude: interfazetik eta zereginetatik.
- Interfazetik. Edukiak panelen atalak bikoizten ditu. Hori gertatzen zen ISPsistemaren dokumentazio zaharrean.
- Zereginetatik. Artikuluen eta atalen izenburuek erabiltzaileen zereginak islatzen dituzte; Tituluek ia beti izaten dituzte aditzak eta βnolaβ galderaren erantzunak. Orain formatu honetara pasatzen ari gara.
Aukeratzen duzun planteamendua edozein dela ere, ziurtatu gaia erabiltzaileek bilatzen dutenari dagokiona dela eta erabiltzailearen galderari bereziki erantzuten dion moduan lantzen dela.
Konfiguratu bilaketa zentralizatua. Mundu ideal batean, bilaketak funtzionatu beharko luke ortografia gaizki edo hizkuntzarekin akatsen bat egin arren. Orain arte Confluencen egin dugun bilaketak ezin gaitu honekin poztu. Produktu asko badituzu eta dokumentazioa orokorra bada, egokitu bilaketa erabiltzailea dagoen orrialdera. Gure kasuan, orrialde nagusiko bilaketak produktu guztietan funtzionatzen du, eta dagoeneko atal zehatz batean bazaude, bertan dauden artikuluetarako bakarrik.
Gehitu edukia eta ogi-apurrak. Ona da orrialde bakoitzak menu bat eta ogi-apurrak dituenean - erabiltzaileak uneko orrialderako bidea edozein mailatara itzultzeko gaitasuna duena. ISPsystemeko dokumentazio zaharrean, artikulutik irten behar zen edukira iristeko. Deserosoa zen, beraz, berrian konpondu genuen.
Jarri estekak produktuan. Jendea behin eta berriz laguntza ematera etortzen bada galdera berdinarekin, zentzuzkoa da interfazeari bere irtenbidearekin iradokizun bat gehitzea. Erabiltzaile batek arazoren bat jasaten duenean datuak edo ikuspegiak badituzu, posta-zerrenda batekin ere jakinaraz diezaiokezu. Erakutsi kezka eta kendu zama laguntzari.
Pop-up leihoaren eskuinaldean DNSSEC konfiguratzeari buruzko artikulu baterako esteka dago ISPmanager-eko domeinuen kudeaketa atalean.
Ezarri erreferentzia gurutzatuak dokumentazioaren barruan. Elkarrekin erlazionatuta dauden artikuluak "loturak" egon behar dira. Artikuluak sekuentzialak badira, ziurtatu testu bakoitzaren amaieran aurrera eta atzera geziak gehitzen dituzula.
Seguruenik, pertsona bat lehenik eta behin bere galderaren erantzun baten bila joango da ez zuri, bilatzaile bati baizik. Pena da arrazoi teknikoengatik han dokumentaziorako estekarik ez egotea. Beraz, zaindu bilaketa-motorren optimizazioa.
4. arazoa. Diseinu zaharkituak pertzepzioa oztopatzen du
Testu txarrez gain, diseinuaren arabera dokumentazioa hondatu daiteke. Jendea ohituta dago ondo idatzitako materialak irakurtzera. Blogak, sare sozialak, komunikabideak - Eduki guztiak ederrak ez ezik, irakurtzeko errazak eta begietarako atseginak ere aurkezten dira. Hori dela eta, erraz uler dezakezu beheko pantaila-argazkian bezala testua ikusten duen pertsona baten mina.
Artikulu honetan pantaila-argazki eta aipagarri asko daude, ez dutela laguntzen, baizik eta pertzepzioa oztopatzen dutela (argazkia klikagarria da)
Ez zenuke efektu mordoa duen dokumentaziotik irakurketa luzerik egin behar, baina oinarrizko arauak kontuan hartu behar dituzu.
Diseinua. Zehaztu gorputz testuaren zabalera, letra-tipoa, tamaina, goiburuak eta betegarria. Kontratatu diseinatzaile bat, eta lana onartzeko edo zuk zeuk egiteko, irakurri Artyom Gorbunov-en "Tipografia eta diseinua" liburua. Diseinuaren ikuspegi bakarra aurkezten du, baina nahikoa da.
Esleipenak. Zehaztu zer azpimarratu behar duen testuan. Normalean hau interfazearen bide bat da, botoiak, kode-txertaketak, konfigurazio fitxategiak, "Kontuan izan" blokeak. Elementu horien esleipenak zeintzuk izango diren zehaztu eta erregelamendu bidez erregistratu. Kontuan izan zenbat eta isuri gutxiago, orduan eta hobeto. Asko daudenean, testua zaratatsua da. Komatxoek ere zarata sortzen dute maizegi erabiltzen badira.
Screenshots. Taldearekin adostu zein kasutan behar diren pantaila-argazkiak. Zalantzarik gabe, ez dago urrats bakoitza ilustratu beharrik. Pantaila-argazki ugari, barne. bereizitako botoiak, pertzepzioa oztopatu, diseinua hondatu. Zehaztu tamaina, baita nabarmentzen eta sinaduren formatua pantaila-argazkietan, eta erregistratu araudian. Gogoratu ilustrazioak beti idatzitakoarekin bat etorri behar direla eta garrantzitsuak izan. Berriz ere, produktua aldizka eguneratzen bada, zaila izango da guztion jarraipena egitea.
Testuaren luzera. Saihestu artikulu luzeegiak. Banatu zatitan, eta hori ezinezkoa bada, gehitu aingura estekak dituzten edukiak artikuluaren hasieran. Artikulu bat bisualki laburragoa izateko modu sinple bat irakurle zirkulu estu batek behar dituen xehetasun teknikoak spoiler baten azpian ezkutatzea da.
formatuak. Konbinatu hainbat formatu zure artikuluetan: testua, bideoa eta irudiak. Horrek pertzepzioa hobetuko du.
Ez saiatu diseinu eder batekin arazoak estaltzen. Egia esanda, guk geuk espero genuen "bilgarriak" dokumentazio zaharkitua gordeko zuela - ez zuen funtzionatu. Testuek hainbeste zarata bisual eta alferrikako xehetasunak zituzten, non araudiak eta diseinu berriak indarrik gabe geratu ziren.
Aurrekoaren zati handi bat dokumentaziorako erabiltzen duzun plataformak zehaztuko du. Adibidez, Confluence dugu. Berarekin ere txikitu behar izan nuen. Interesa baduzu, irakurri gure web garatzailearen istorioa: .
Non hasi hobetzen eta nola bizirik irauten
Zure dokumentazioa ISPsistemarena bezain zabala bada eta ez badakizu nondik hasi, hasi arazo handienekin. Bezeroek ez dute dokumentua ulertzen - testuak hobetu, arauak egin, idazleak prestatu. Dokumentazioa zaharkituta dago - zaindu barne-prozesuak. Hasi produktu ezagunenei buruzko artikulu ezagunenekin: eskatu laguntza, begiratu guneen analisiak eta bilatzaileetako kontsultak.
Demagun berehala - ez da erraza izango. Eta nekez funtzionatuko du azkar ere. Hasi berria ez bazara eta gauza zuzena berehala egin ezean. Ziur dakigun gauza bat da denborarekin hobetuko dela. Baina prozesua ez da inoiz amaituko :-).
Iturria: www.habr.com