Ang dokumentasyon sa software usa lamang ka hugpong sa mga artikulo. Apan bisan sila makahimo kanimo nga buang. Una, mogugol ka ug taas nga panahon sa pagpangita sa gikinahanglang mga instruksyon. Unya masabtan nimo ang dili klaro nga teksto. Gibuhat nimo ang nahisulat, apan ang problema wala masulbad. Nangita ka ug laing artikulo, gikulbaan ka... Paglabay sa usa ka oras gibiyaan nimo ang tanan ug mibiya. Ingon niini kung giunsa ang dili maayo nga dokumentasyon molihok. Unsa ang naghimo niini nga ingon niini ug kung giunsa kini pag-ayo - basaha sa ilawom sa pagputol.
Adunay daghang mga kakulangan sa among daan nga dokumentasyon. Gibuhat namo kini pag-usab hapit sa usa ka tuig na aron ang senaryo nga gihulagway sa ibabaw dili makaapekto sa among mga kliyente. Tan-awa, ΠΈ .
Problema 1: Dili klaro, dili maayo nga pagkasulat nga mga artikulo
Kung imposible nga masabtan ang dokumentasyon, unsa ang punto niini? Apan walay usa nga nagsulat sa dili masabtan nga mga artikulo sa katuyoan. Nahitabo kini kung ang tagsulat wala maghunahuna bahin sa mamiminaw ug katuyoan, nagbubo og tubig ug wala magsusi sa teksto alang sa mga sayup.
- Ang mamiminaw. Sa dili pa magsulat og usa ka artikulo, kinahanglan nimong hunahunaon ang lebel sa pagpangandam sa magbabasa. Makataronganon nga sa usa ka artikulo alang sa usa ka bag-ohan dili nimo laktawan ang sukaranan nga mga lakang ug ibilin ang mga teknikal nga termino nga walaβy katin-awan, apan sa usa ka artikulo sa usa ka talagsaon nga bahin nga kinahanglan ra sa mga propesyonal, kinahanglan nimo nga ipasabut ang kahulugan sa pulong nga PHP.
- Tumong. Usa pa ka butang nga hunahunaon daan. Ang tagsulat kinahanglang maghimo ug tin-aw nga tumong, matino ang mapuslanong epekto sa artikulo, ug magdesisyon kon unsay buhaton sa magbabasa human kini mabasa. Kung wala kini nahimo, mahuman ka sa paghulagway alang sa paghulagway.
- Tubig ug mga bug. Adunay daghang wala kinahanglana nga kasayuran ug burukrasya, mga sayup ug typos nga nakabalda sa panan-aw. Bisan kung ang magbabasa dili usa ka gramatika nazi, ang pagkawalay pagtagad sa teksto mahimong makapalong kaniya.
Hunahunaa ang mga tip sa ibabaw, ug ang mga artikulo mahimong mas klaro - garantiya. Aron mahimo kini nga mas maayo, gamita ang among .
Problema 2. Ang mga artikulo dili motubag sa tanang pangutana
Daotan kung ang dokumentasyon dili magpadayon sa pag-uswag, dili motubag sa tinuod nga mga pangutana, ug ang mga sayup niini dili matul-id sulod sa mga katuigan. Kini ang mga problema dili kaayo sa tagsulat, apan sa organisasyon sa mga proseso sa sulod sa kompanya.
Ang dokumentasyon wala makasunod sa pag-uswag
Ang bahin anaa na sa pagpagawas, plano sa marketing sa pagtabon niini, ug unya kini turns nga ang bag-ong artikulo o hubad wala pa sa dokumentasyon. Kinahanglan pa gani namo nga i-postpone ang pagpagawas tungod niini. Mahimo nimong hangyoon ang tanan nga itugyan ang mga buluhaton sa mga teknikal nga magsusulat sa oras kung gusto nimo, apan dili kini molihok. Kung ang proseso dili awtomatiko, ang sitwasyon magbalikbalik sa kaugalingon.
Naghimo kami mga pagbag-o sa YouTrack. Ang tahas sa pagsulat sa usa ka artikulo bahin sa usa ka bag-ong bahin nahulog sa teknikal nga magsusulat sa parehas nga higayon kung ang bahin nagsugod sa pagsulay. Dayon ang marketing makakat-on mahitungod niini aron makapangandam alang sa promosyon. Ang mga pahibalo moabut usab sa Mattermost corporate messenger, mao nga imposible nga makalimtan ang mga balita gikan sa mga developer.
Ang dokumentasyon wala magpakita sa mga hangyo sa tiggamit
Naanad na kami sa pagtrabaho nga sama niini: usa ka bahin ang migawas, among gihisgutan kini. Gihubit namo kon unsaon kini pag-on, pagpalong niini, ug paghimog maayong mga kausaban. Apan unsa man kon ang usa ka kliyente naggamit sa among software sa paagi nga wala namo damha? O aduna ba kini mga sayop nga wala nato mahunahuna?
Aron masiguro nga ang dokumentasyon ingon ka kompleto kutob sa mahimo, among girekomenda ang pag-analisar sa mga hangyo sa suporta, mga pangutana sa tema nga mga forum, ug mga pangutana sa mga search engine. Ang pinakasikat nga mga topiko ibalhin ngadto sa mga teknikal nga magsusulat aron sila makadugang sa kasamtangan nga mga artikulo o magsulat og mga bag-o.
Ang dokumentasyon wala gipauswag
Lisud ang pagbuhat niini sa hingpit diha-diha dayon; aduna gihapoy mga sayop. Makalaum ka alang sa feedback gikan sa mga kustomer, apan dili tingali nga ilang i-report ang matag typo, dili tukma, dili masabtan o dili makit-an nga artikulo. Dugang sa mga kliyente, gibasa sa mga empleyado ang dokumentasyon, nga nagpasabut nga nakita nila ang parehas nga mga sayup. Mahimo kining gamiton! Kinahanglan lang nga maghimo ka og mga kondisyon diin sayon ββββang pagreport sa usa ka problema.
Adunay kami usa ka grupo sa internal nga portal diin ang mga empleyado nagbilin mga komento, sugyot ug ideya sa dokumentasyon. Nagkinahanglan ba ang suporta ug usa ka artikulo, apan wala kini? Namatikdan ba sa tester ang pagkadili tukma? Nagreklamo ba ang kauban sa mga tagdumala sa kalamboan bahin sa mga sayup? Tanan sa kini nga grupo! Ang mga teknikal nga magsusulat nag-ayo dayon sa pipila ka mga butang, nagbalhin sa pipila ka mga butang sa YouTrack, ug naghatag sa uban og panahon sa paghunahuna. Aron mapugngan ang hilisgutan gikan sa pagkamatay, matag karon ug unya gipahinumdoman ka namon sa paglungtad sa grupo ug ang kamahinungdanon sa feedback.
Problema 3. Nagkinahanglan ug taas nga panahon sa pagpangita sa hustong artikulo.
Ang usa ka artikulo nga dili makit-an dili mas maayo kaysa usa ka artikulo nga dili makit-an. Ang motto sa maayong dokumentasyon kinahanglan nga "Dali pangitaon, dali pangitaon." Unsaon pagkab-ot niini?
Pag-organisar sa istruktura ug pagtino sa prinsipyo sa pagpili sa mga hilisgutan. Ang istruktura kinahanglan nga ingon ka transparent kutob sa mahimo aron ang magbabasa dili maghunahuna, "Asa nako makit-an kini nga artikulo?" Sa pag-summarize, adunay duha ka mga pamaagi: gikan sa interface ug gikan sa mga buluhaton.
- Gikan sa interface. Ang sulod nagdoble sa mga seksyon sa panel. Kini ang kaso sa daan nga dokumentasyon sa ISPsystem.
- Gikan sa mga buluhaton. Ang mga titulo sa mga artikulo ug mga seksyon nagpakita sa mga buluhaton sa mga tiggamit; Ang mga titulo hapit kanunay adunay mga berbo ug mga tubag sa "unsaon" nga pangutana. Karon kita mobalhin sa niini nga format.
Bisan unsa nga pamaagi ang imong pilion, siguroha nga ang hilisgutan may kalabutan sa kung unsa ang gipangita sa mga tiggamit ug nasakup sa usa ka paagi nga piho nga nagtubag sa pangutana sa gumagamit.
Paghimo ug sentralisadong pagpangita. Sa usa ka sulundon nga kalibutan, ang pagpangita kinahanglan molihok bisan kung nasayop ka sa spelling o nasayop sa pinulongan. Ang among pagpangita sa Confluence hangtod karon dili makapahimuot kanamo niini. Kung ikaw adunay daghang mga produkto ug ang dokumentasyon kasagaran, ipahiangay ang pagpangita sa panid nga naa sa tiggamit. Sa among kaso, ang pagpangita sa panguna nga panid nagtrabaho alang sa tanan nga mga produkto, ug kung naa ka na sa usa ka piho nga seksyon, nan alang lamang sa mga artikulo niini.
Idugang ang sulod ug mga breadcrumb. Maayo kung ang matag panid adunay menu ug mga breadcrumb - ang agianan sa tiggamit sa kasamtangan nga panid nga adunay katakus nga makabalik sa bisan unsang lebel. Sa daan nga dokumentasyon sa ISPsystem, kinahanglan nimo nga mogawas sa artikulo aron makuha ang sulud. Dili kombenyente, mao nga giayo namo kini sa bag-o.
Ibutang ang mga link sa produkto. Kung ang mga tawo kanunay nga nagsuporta sa parehas nga pangutana, makatarunganon nga magdugang usa ka pahiwatig sa solusyon niini sa interface. Kung ikaw adunay datos o panabut kung ang usa ka tiggamit nakasinati usa ka problema, mahimo nimo usab nga pahibal-an sila sa usa ka lista sa pagpadala. Ipakita kanila ang kabalaka ug kuhaa ang palas-anon gikan sa suporta.
Sa tuo sa pop-up nga bintana adunay usa ka link sa usa ka artikulo bahin sa pag-set up sa DNSSEC sa seksyon sa pagdumala sa domain sa ISPmanager.
I-set up ang mga cross-reference sulod sa dokumentasyon. Ang mga artikulo nga adunay kalabutan sa usag usa kinahanglan nga "gisumpay". Kung ang mga artikulo sunud-sunod, siguruha nga idugang ang unahan ug paatras nga mga pana sa katapusan sa matag teksto.
Lagmit, ang usa ka tawo una nga mangita alang sa tubag sa iyang pangutana dili kanimo, apan sa usa ka search engine. Makauulaw kung walay mga link sa dokumentasyon didto tungod sa teknikal nga mga rason. Busa pag-atiman sa search engine optimization.
Problema 4. Ang outdated nga layout nakabalda sa perception
Dugang pa sa dili maayo nga mga teksto, ang dokumentasyon mahimong madaot sa disenyo. Ang mga tawo naanad sa pagbasa sa maayong pagkasulat nga mga materyal. Mga blog, social network, media - ang tanan nga sulud gipresentar dili lamang matahum, apan dali usab basahon ug makapahimuot sa mata. Busa, dali nimo masabtan ang kasakit sa usa ka tawo nga nakakita sa teksto sama sa screenshot sa ubos.
Adunay daghang mga screenshot ug mga highlight sa kini nga artikulo nga dili kini makatabang, apan makabalda lamang sa panan-aw (ang hulagway ma-click)
Dili ka kinahanglan maghimo usa ka taas nga pagbasa gikan sa dokumentasyon nga adunay daghang mga epekto, apan kinahanglan nimo nga tagdon ang sukaranan nga mga lagda.
Layout. Tinoa ang gilapdon sa teksto sa lawas, font, gidak-on, mga ulohan, ug padding. Pag-abang og usa ka tigdesinyo, ug aron dawaton ang trabaho o buhata kini sa imong kaugalingon, basaha ang libro ni Artyom Gorbunov nga "Typography and Layout." Nagpresentar lamang kini og usa ka panglantaw sa layout, apan kini igo na.
Mga Alokasyon. Tinoa kon unsa ang nagkinahanglan og gibug-aton sa teksto. Kasagaran kini usa ka agianan sa interface, mga buton, pagsal-ot sa code, mga file sa pag-configure, "Palihug timan-i" nga mga bloke. Tinoa kung unsa ang mga alokasyon niini nga mga elemento ug irekord kini sa mga regulasyon. Hinumdomi nga ang gamay nga pag-discharge, mas maayo. Kung daghan sila, saba ang text. Bisan ang mga marka sa kinutlo makamugna og kasaba kung kini gigamit kanunay.
Mga tanghaga. Pag-uyon sa team kung unsang mga kaso ang kinahanglan nga mga screenshot. Dili kinahanglan nga ihulagway ang matag lakang. Daghang mga screenshot, lakip. bulag nga mga buton, makabalda sa panan-aw, makadaut sa layout. Tinoa ang gidak-on, ingon man ang format sa mga highlight ug pirma sa mga screenshot, ug irekord kini sa mga regulasyon. Hinumdumi nga ang mga ilustrasyon kinahanglan kanunay nga katumbas sa kung unsa ang gisulat ug adunay kalabotan. Pag-usab, kung ang produkto kanunay nga gi-update, lisud ang pagsubay sa tanan.
Ang gitas-on sa teksto. Likayi ang sobra ka taas nga mga artikulo. Bahina kini sa mga bahin, ug kung dili kini mahimo, idugang ang sulud nga adunay mga link sa angkla sa sinugdanan sa artikulo. Usa ka yano nga paagi sa paghimo sa usa ka artikulo nga biswal nga mas mubo mao ang pagtago sa teknikal nga mga detalye nga gikinahanglan sa usa ka pig-ot nga lingin sa mga magbabasa ubos sa usa ka spoiler.
Mga format. Paghiusa sa daghang mga format sa imong mga artikulo: teksto, video ug mga imahe. Kini makapauswag sa panglantaw.
Ayaw pagsulay sa pagtabon sa mga problema sa matahum nga layout. Sa tinuud, kami mismo naglaum nga ang "wrapper" makaluwas sa karaan nga dokumentasyon - wala kini molihok. Ang mga teksto adunay daghang biswal nga kasaba ug wala kinahanglana nga mga detalye nga ang mga regulasyon ug bag-ong disenyo walay gahum.
Kadaghanan sa nahisgutan sa ibabaw matino sa plataporma nga imong gigamit alang sa dokumentasyon. Pananglitan, kita adunay Confluence. Kinahanglan ko usab nga makigsulti kaniya. Kung interesado, basaha ang istorya sa among web developer: .
Asa magsugod sa pag-uswag ug unsaon pagkinabuhi
Kung ang imong dokumentasyon sama ka lapad sa ISPsystem ug wala ka mahibal-an kung asa magsugod, magsugod sa labing dagkong mga problema. Ang mga kliyente wala makasabut sa dokumento - pagpalambo sa mga teksto, paghimo og mga regulasyon, pagbansay sa mga magsusulat. Ang dokumentasyon wala na sa petsa - atimana ang mga internal nga proseso. Pagsugod sa labing inila nga mga artikulo bahin sa labing inila nga mga produkto: pangayo og suporta, tan-awa ang analytics sa site ug mga pangutana sa mga search engine.
Ingnon ta dayon - dili kini sayon. Ug kini dili tingali molihok dayon. Gawas lang kung nagsugod ka ug buhaton dayon ang husto. Usa ka butang nga nahibal-an namon nga sigurado mao nga kini moarang-arang sa paglabay sa panahon. Apan ang proseso dili matapos :-).
Source: www.habr.com