Programaro dokumentado estas nur aro de artikoloj. Sed eĉ ili povas frenezigi vin. Unue, vi pasigas longan tempon serĉante la necesajn instrukciojn. Tiam vi komprenas la malklaran tekston. Vi faras kiel skribite, sed la problemo ne estas solvita. Vi serĉas alian artikolon, vi nervoziĝas... Post unu horo vi rezignas pri ĉio kaj foriras. Tiel funkcias malbona dokumentado. Kio faras ĝin tiel kaj kiel ripari ĝin - legu sub la tranĉo.
Estis multaj mankoj en nia malnova dokumentaro. Ni relaboras ĝin dum preskaŭ unu jaro por ke la scenaro priskribita supre ne influu niajn klientojn. Rigardu, и .
Problemo 1: Neklaraj, malbone skribitaj artikoloj
Se la dokumentado estas neeble komprenebla, kio estas la signifo de ĝi? Sed neniu intence verkas nekompreneblajn artikolojn. Ili okazas kiam la aŭtoro ne pensas pri la publiko kaj celo, verŝas akvon kaj ne kontrolas la tekston por eraroj.
- Aŭdienco. Antaŭ ol verki artikolon, vi devas pensi pri la nivelo de preparado de la leganto. Estas logike, ke en artikolo por komencanto vi ne saltu la bazajn paŝojn kaj lasu teknikajn terminojn sen klarigo, sed en artikolo pri malofta trajto, kiun bezonas nur profesiuloj, vi klarigu la signifon de la vorto PHP.
- Golo. Ankoraŭ unu afero por pripensi antaŭe. La aŭtoro devas fiksi klaran celon, determini la utilan efikon de la artikolo kaj decidi kion faros la leganto post legado de ĝi. Se ĉi tio ne estas farita, vi finos kun priskribo pro priskribo.
- Akvo kaj cimoj. Estas multe da nenecesaj informoj kaj burokratio, eraroj kaj tajperaroj malhelpas percepton. Eĉ se la leganto ne estas gramatika nazio, nezorgemo en la teksto povas malŝalti lin.
Konsideru la suprajn konsiletojn, kaj la artikoloj fariĝos pli klaraj - garantiite. Por fari ĝin eĉ pli bona, uzu nian .
Problemo 2. Artikoloj ne respondas ĉiujn demandojn
Estas malbone kiam la dokumentaro ne sekvas evoluadon, ne respondas verajn demandojn, kaj eraroj en ĝi ne estas korektitaj dum jaroj. Ĉi tiuj estas problemoj ne tiom de la aŭtoro, sed de la organizado de procezoj ene de la kompanio.
Dokumentado ne sekvas la evoluon
La funkcio jam estas en eldono, merkatado planas kovri ĝin, kaj tiam rezultas, ke la nova artikolo aŭ traduko ankoraŭ ne estas en la dokumentado. Ni eĉ devis prokrasti la liberigon pro tio. Vi povas peti ĉiujn transdoni taskojn al teknikaj verkistoj ĝustatempe kiom vi volas, sed ĝi ne funkcios. Se la procezo ne estas aŭtomatigita, la situacio ripetiĝos.
Ni faris ŝanĝojn al YouTrack. La tasko verki artikolon pri nova funkcio falas al la teknika verkisto en la sama momento, kiam la funkcio komencas esti provita. Tiam merkatado lernas pri ĝi por prepari por reklamado. Sciigoj ankaŭ venas al la kompania mesaĝisto Mattermost, do estas simple neeble maltrafi novaĵojn de programistoj.
Dokumentado ne reflektas uzantpetojn
Ni kutimas labori tiel: aperis trajto, ni parolis pri ĝi. Ni priskribis kiel ŝalti ĝin, malŝalti ĝin kaj fari bonajn ĝustigojn. Sed kio se kliento uzas nian programaron en maniero kiel ni ne atendis? Aŭ ĉu ĝi havas erarojn, pri kiuj ni ne pensis?
Por certigi, ke la dokumentaro estas kiel eble plej kompleta, ni rekomendas analizi subtenajn petojn, demandojn pri temaj forumoj kaj demandojn en serĉiloj. La plej popularaj temoj estos transdonitaj al teknikaj verkistoj por ke ili povu kompletigi ekzistantajn artikolojn aŭ verki novajn.
Dokumentado ne estas plibonigata
Estas malfacile fari ĝin perfekte tuj; ankoraŭ estos eraroj. Vi povas esperi pri sugestoj de klientoj, sed estas neverŝajne, ke ili raportos ĉiun tajperaron, malprecizaĵon, nekompreneblan aŭ netrovitan artikolon. Krom klientoj, dungitoj legas la dokumentaron, kio signifas, ke ili vidas la samajn erarojn. Ĉi tio povas esti uzata! Vi nur bezonas krei kondiĉojn en kiuj estos facile raporti problemon.
Ni havas grupon en la interna portalo, kie dungitoj lasas komentojn, sugestojn kaj ideojn pri dokumentado. Ĉu subteno bezonas artikolon, sed ĝi ne ekzistas? Ĉu la testinto rimarkis la malprecizecon? Ĉu la partnero plendis al evoluaj administrantoj pri eraroj? Ĉiuj en ĉi tiu grupo! Teknikaj verkistoj tuj riparas iujn aferojn, transdonas kelkajn aferojn al YouTrack kaj donas al aliaj iom da tempo por pripensi. Por eviti ke la temo formortu, de tempo al tempo ni memorigas al vi la ekziston de la grupo kaj la gravecon de reagoj.
Problemo 3. Necesas longa tempo por trovi la ĝustan artikolon.
Artikolo trovebla ne estas pli bona ol artikolo netrovebla. La devizo de bona dokumentado devus esti "Facile serĉebla, facile trovebla." Kiel atingi ĉi tion?
Organizi la strukturon kaj determini la principon por elekti temojn. La strukturo estu kiel eble plej travidebla por ke la leganto ne pensu: "Kie mi povas trovi ĉi tiun artikolon?" Por resumi, estas du aliroj: de la interfaco kaj de la taskoj.
- De la interfaco. La enhavo duobligas la panelajn sekciojn. Tio estis la kazo en la malnova ISPsystem-dokumentado.
- De taskoj. La titoloj de artikoloj kaj sekcioj reflektas la taskojn de la uzantoj; Titoloj preskaŭ ĉiam enhavas verbojn kaj respondojn al la demando "kiel al". Nun ni moviĝas al ĉi tiu formato.
Kian ajn aliron vi elektas, certigu, ke la temo rilatas al tio, kion uzantoj serĉas kaj estas kovrita en maniero, kiu specife traktas la demandon de la uzanto.
Agordu centralizitan serĉon. En ideala mondo, serĉo devus funkcii eĉ kiam vi misliterumas aŭ faras eraron kun la lingvo. Nia serĉado en Confluence ĝis nun ne povas plaĉi al ni per tio. Se vi havas multajn produktojn kaj la dokumentado estas ĝenerala, adaptu la serĉon al la paĝo, sur kiu la uzanto estas. En nia kazo, la serĉo sur la ĉefa paĝo funkcias por ĉiuj produktoj, kaj se vi jam estas en specifa sekcio, tiam nur por la artikoloj en ĝi.
Aldonu enhavon kaj panpecetojn. Estas bone, kiam ĉiu paĝo havas menuon kaj panetojn - la vojo de la uzanto al la nuna paĝo kun la kapablo reveni al ajna nivelo. En la malnova ISPsystem-dokumentado, vi devis eliri la artikolon por atingi la enhavon. Estis maloportuna, do ni riparis ĝin en la nova.
Metu ligilojn en la produkton. Se homoj venas por subteni denove kaj ree kun la sama demando, estas senco aldoni sugeston kun ĝia solvo al la interfaco. Se vi havas datumojn aŭ sciojn pri kiam uzanto spertas problemon, vi ankaŭ povas sciigi ilin per dissendolisto. Montru al ili zorgon kaj forprenu la ŝarĝon de subteno.
Dekstre en la ŝprucfenestro estas ligilo al artikolo pri agordo de DNSSEC en la sekcio pri administrado de domajno de ISPmanager.
Agordu krucreferencojn ene de dokumentaro. Artikoloj, kiuj rilatas unu al la alia, estu "ligitaj". Se la artikoloj estas sinsekvaj, nepre aldonu antaŭen kaj malantaŭen sagojn ĉe la fino de ĉiu teksto.
Plej verŝajne, homo unue serĉos respondon al sia demando ne al vi, sed al serĉilo. Estas domaĝe, se ne ekzistas ligiloj al la dokumentaro tie pro teknikaj kialoj. Do zorgu pri serĉilo-optimumigo.
Problemo 4. Malmoderna aranĝo malhelpas percepton
Krom malbonaj tekstoj, dokumentaro povas esti difektita pro dezajno. Homoj kutimas legi bone verkitajn materialojn. Blogoj, sociaj retoj, amaskomunikiloj - ĉiu enhavo estas prezentita ne nur bela, sed ankaŭ facile legebla kaj plaĉa al la okulo. Sekve, vi povas facile kompreni la doloron de homo, kiu vidas tekston kiel en la ekrankopio sube.
Estas tiom da ekrankopioj kaj elstaraĵoj en ĉi tiu artikolo, ke ili ne helpas, sed nur malhelpas percepton (la bildo estas klakebla)
Vi ne devus legi longe el la dokumentaro kun amaso da efikoj, sed vi devas konsideri la bazajn regulojn.
Aranĝo. Determini korpan tekston larĝon, tiparon, grandecon, titolojn kaj kompletigo. Dungu dezajniston, kaj por akcepti la laboron aŭ fari ĝin mem, legu la libron de Artjom Gorbunov "Tipografio kaj Aranĝo". Ĝi prezentas nur unu vidon de la aranĝo, sed ĝi estas sufiĉe sufiĉa.
Asignoj. Determini kio postulas emfazon en la teksto. Tipe ĉi tio estas vojo en la interfaco, butonoj, kodaj enmetoj, agordaj dosieroj, "Bonvolu noti" blokoj. Determini kiaj estos la atribuoj de ĉi tiuj elementoj kaj registri ilin en la regularoj. Memoru, ke ju malpli da malŝarĝo, des pli bone. Kiam estas multaj, la teksto estas brua. Eĉ citiloj kreas bruon se ili estas uzataj tro ofte.
Ekrankopioj. Akordiĝu kun la teamo en kiuj kazoj necesas ekrankopioj. Certe ne necesas ilustri ĉiun paŝon. Granda nombro da ekrankopioj, inkl. apartaj butonoj, malhelpi percepton, difekti la aranĝon. Determinu la grandecon, same kiel la formaton de kulminaĵoj kaj subskriboj sur ekrankopioj, kaj registri ilin en la regularoj. Memoru, ke ilustraĵoj ĉiam devas respondi al tio, kio estas skribita kaj esti trafaj. Denove, se la produkto estas ĝisdatigita regule, estos malfacile observi ĉiujn.
Longo de teksto. Evitu tro longajn artikolojn. Rompi ilin en partojn, kaj se tio ne eblas, aldonu enhavon kun ankraj ligiloj al la komenco de la artikolo. Simpla maniero fari artikolon vide pli mallonga estas kaŝi teknikajn detalojn necesajn de mallarĝa rondo de legantoj sub spoiler.
Formatoj. Kombinu plurajn formatojn en viaj artikoloj: teksto, video kaj bildoj. Ĉi tio plibonigos la percepton.
Ne provu kaŝi problemojn per bela aranĝo. Sincere, ni mem esperis, ke la "envolvaĵo" ŝparos la malmodernan dokumentadon - ĝi ne funkciis. La tekstoj enhavis tiom da vida bruo kaj nenecesaj detaloj ke la regularoj kaj nova dezajno estis senpovaj.
Multo de ĉi-supraj estos determinita de la platformo, kiun vi uzas por dokumentado. Ekzemple, ni havas Confluence. Ankaŭ mi devis palpi kun li. Se interesiĝas, legu la rakonton de nia retejo-programisto: .
Kie komenci pliboniĝi kaj kiel postvivi
Se via dokumentaro estas tiel vasta kiel tiu de ISPsistemo kaj vi ne scias kie komenci, komencu kun la plej grandaj problemoj. Klientoj ne komprenas la dokumenton - plibonigu la tekstojn, faru regularon, trejnu verkistojn. Dokumentado estas malaktuala - zorgu pri internaj procezoj. Komencu per la plej popularaj artikoloj pri la plej popularaj produktoj: petu subtenon, rigardu retejo-analitikojn kaj demandojn en serĉiloj.
Ni diru tuj - ne estos facile. Kaj ankaŭ ne verŝajne funkcios rapide. Krom se vi ĵus komencas kaj faras la ĝustan aferon tuj. Unu afero, kiun ni scias certe, estas, ke ĝi pliboniĝos kun la tempo. Sed la procezo neniam finiĝos :-).
fonto: www.habr.com