Sagtewaredokumentasie is net 'n stel artikels. Maar selfs hulle kan jou mal maak. Eerstens spandeer jy lank op soek na die nodige instruksies. Dan verstaan jy die obskure teks. Jy doen soos geskryf, maar die probleem is nie opgelos nie. Jy soek nog 'n artikel, jy raak senuweeagtig... 'n Uur later gee jy alles op en vertrek. Dit is hoe slegte dokumentasie werk. Wat maak dit so en hoe om dit reg te maak - lees onder die snit.
Daar was baie tekortkominge in ons ou dokumentasie. Ons herwerk dit nou al amper 'n jaar sodat die scenario wat hierbo beskryf word nie ons kliënte raak nie. Kyk, и .
Probleem 1: Onduidelike, swak geskrewe artikels
As die dokumentasie onmoontlik is om te verstaan, wat is die punt daarvan? Maar niemand skryf doelbewus onverstaanbare artikels nie. Dit gebeur wanneer die skrywer nie aan die gehoor en doel dink nie, water gooi en nie die teks vir foute nagaan nie.
- gehoor. Voordat jy 'n artikel skryf, moet jy nadink oor die leser se voorbereidingsvlak. Dit is logies dat jy in 'n artikel vir 'n beginner nie die basiese stappe moet oorslaan en tegniese terme sonder verduideliking moet los nie, maar in 'n artikel oor 'n seldsame kenmerk wat net professionele mense nodig het, moet jy die betekenis van die woord PHP verduidelik.
- Doel. Nog iets om vooraf oor na te dink. Die skrywer moet 'n duidelike doelwit stel, die nuttige effek van die artikel bepaal en besluit wat die leser sal doen nadat hy dit gelees het. As dit nie gedoen word nie, sal jy ter wille van beskrywing met beskrywing eindig.
- Water en goggas. Daar is baie onnodige inligting en burokrasie, foute en tikfoute belemmer persepsie. Selfs al is die leser nie ’n grammatika-nazi nie, kan sorgeloosheid in die teks hom afskakel.
Oorweeg die wenke hierbo, en die artikels sal duideliker word - gewaarborg. Om dit nog beter te maak, gebruik ons .
Probleem 2. Artikels beantwoord nie alle vrae nie
Dit is erg wanneer die dokumentasie nie tred hou met ontwikkeling nie, nie werklike vrae beantwoord nie, en foute daarin word vir jare nie reggestel nie. Dit is probleme nie soseer van die skrywer nie, maar van die organisasie van prosesse binne die maatskappy.
Dokumentasie hou nie tred met ontwikkeling nie
Die kenmerk is reeds vrygestel, bemarking beplan om dit te dek, en dan blyk dit dat die nuwe artikel of vertaling steeds nie in die dokumentasie is nie. Ons moes selfs die vrylating as gevolg hiervan uitstel. Jy kan almal vra om take betyds aan tegniese skrywers te oorhandig soveel jy wil, maar dit sal nie werk nie. As die proses nie geoutomatiseer is nie, sal die situasie homself herhaal.
Ons het veranderinge aan YouTrack aangebring. Die taak om 'n artikel oor 'n nuwe kenmerk te skryf, val op die tegniese skrywer op dieselfde oomblik wanneer die kenmerk begin getoets word. Dan leer bemarking daarvan om voor te berei vir bevordering. Kennisgewings kom ook na die Mattermost korporatiewe boodskapper, so dit is eenvoudig onmoontlik om nuus van ontwikkelaars te mis.
Dokumentasie weerspieël nie gebruikersversoeke nie
Ons is gewoond daaraan om so te werk: 'n kenmerk het uitgekom, ons het daaroor gepraat. Ons het beskryf hoe om dit aan te skakel, af te skakel en fyn aanpassings te maak. Maar wat as 'n kliënt ons sagteware gebruik op 'n manier wat ons nie verwag het nie? Of het dit foute waaraan ons nie gedink het nie?
Om te verseker dat die dokumentasie so volledig as moontlik is, beveel ons aan dat ondersteuningsversoeke, vrae oor tematiese forums en navrae in soekenjins ontleed word. Die gewildste onderwerpe sal na tegniese skrywers oorgedra word sodat hulle bestaande artikels kan aanvul of nuwes kan skryf.
Dokumentasie word nie verbeter nie
Dit is moeilik om dit dadelik perfek te doen; daar sal steeds foute wees. Jy kan hoop vir terugvoer van kliënte, maar dit is onwaarskynlik dat hulle elke tikfout, onakkuraatheid, onverstaanbare of ongevonde artikel sal rapporteer. Benewens kliënte, lees werknemers die dokumentasie, wat beteken dat hulle dieselfde foute sien. Dit kan gebruik word! Jy hoef net toestande te skep waarin dit maklik sal wees om 'n probleem aan te meld.
Ons het 'n groep op die interne portaal waar werknemers kommentaar, voorstelle en idees oor dokumentasie laat. Het ondersteuning 'n artikel nodig, maar dit bestaan nie? Het die toetser die onakkuraatheid opgemerk? Het die vennoot by ontwikkelingsbestuurders gekla oor foute? Almal in hierdie groep! Tegniese skrywers stel sommige dinge dadelik reg, dra sommige dinge oor na YouTrack, en gee ander tyd om oor na te dink. Om te verhoed dat die onderwerp doodgaan, herinner ons u van tyd tot tyd aan die bestaan van die groep en die belangrikheid van terugvoer.
Probleem 3. Dit neem lank om die regte artikel te vind.
'n Artikel wat nie gevind kan word nie, is niks beter as 'n artikel wat nie gevind kan word nie. Die leuse van goeie dokumentasie moet wees "Maklik om te soek, maklik om te vind." Hoe om dit te bereik?
Organiseer die struktuur en bepaal die beginsel vir die keuse van onderwerpe. Die struktuur moet so deursigtig as moontlik wees sodat die leser nie dink, "Waar kan ek hierdie artikel vind?" Om op te som, daar is twee benaderings: van die koppelvlak en van die take.
- Van die koppelvlak. Die inhoud dupliseer die paneelafdelings. Dit was die geval in die ou ISP-stelsel dokumentasie.
- Van take. Die titels van artikels en afdelings weerspieël die take van die gebruikers; Titels bevat amper altyd werkwoorde en antwoorde op die "hoe om"-vraag. Nou beweeg ons na hierdie formaat.
Watter benadering jy ook al kies, maak seker dat die onderwerp relevant is vir dit waarna gebruikers soek en gedek word op 'n manier wat spesifiek die gebruiker se vraag aanspreek.
Stel 'n gesentraliseerde soektog op. In 'n ideale wêreld behoort soek te werk selfs wanneer jy verkeerd spel of 'n fout met die taal maak. Ons soektog in Confluence tot dusver kan ons nie hiermee tevrede stel nie. As jy baie produkte het en die dokumentasie is algemeen, pas die soektog aan by die bladsy waarop die gebruiker is. In ons geval werk die soektog op die hoofblad vir alle produkte, en as jy reeds in 'n spesifieke afdeling is, dan net vir die artikels daarin.
Voeg inhoud en broodkrummels by. Dit is goed wanneer elke bladsy 'n spyskaart en broodkrummels het - die gebruiker se pad na die huidige bladsy met die vermoë om terug te keer na enige vlak. In die ou ISP-stelsel-dokumentasie moes jy die artikel verlaat om by die inhoud uit te kom. Dit was ongerieflik, so ons het dit in die nuwe een reggemaak.
Plaas skakels in die produk. As mense oor en oor kom om dieselfde vraag te ondersteun, maak dit sin om 'n wenk met die oplossing daarvan by die koppelvlak by te voeg. As jy data of insig het oor wanneer 'n gebruiker 'n probleem ervaar, kan jy hulle ook met 'n poslys in kennis stel. Toon hulle besorgdheid en neem die las van ondersteuning af.
Aan die regterkant in die opspringvenster is 'n skakel na 'n artikel oor die opstel van DNSSEC in die domeinbestuurafdeling van ISPmanager
Stel kruisverwysings binne dokumentasie op. Artikels wat met mekaar verband hou, moet "gekoppel" wees. As die artikels opeenvolgend is, maak seker dat jy vorentoe en agtertoe pyltjies aan die einde van elke teks byvoeg.
Heel waarskynlik sal 'n persoon eers 'n antwoord op sy vraag gaan soek, nie aan jou nie, maar aan 'n soekenjin. Dit is jammer as daar om tegniese redes geen skakels na die dokumentasie daar is nie. Sorg dus vir soekenjinoptimalisering.
Probleem 4. Verouderde uitleg meng in met persepsie
Benewens slegte tekste, kan dokumentasie deur ontwerp bederf word. Mense is gewoond daaraan om goedgeskrewe materiaal te lees. Blogs, sosiale netwerke, media - alle inhoud word nie net pragtig aangebied nie, maar ook maklik om te lees en 'n lus vir die oog. Daarom kan jy maklik die pyn verstaan van 'n persoon wat teks sien soos in die skermkiekie hieronder.
Daar is soveel skermkiekies en hoogtepunte in hierdie artikel dat dit nie help nie, maar net inmeng met persepsie (die prentjie is klikbaar)
U moet nie 'n langlees uit die dokumentasie met 'n klomp effekte maak nie, maar u moet die basiese reëls in ag neem.
Uitleg. Bepaal liggaamstekswydte, lettertipe, grootte, opskrifte en opvulling. Huur 'n ontwerper, en om die werk te aanvaar of dit self te doen, lees Artyom Gorbunov se boek "Tipografie en uitleg." Dit bied slegs een aansig van die uitleg, maar dit is heeltemal voldoende.
Toekennings. Bepaal wat klem in die teks vereis. Tipies is dit 'n pad in die koppelvlak, knoppies, kode-insetsels, konfigurasielêers, "Let wel" blokke. Bepaal wat die toekennings van hierdie elemente sal wees en teken dit in die regulasies aan. Hou in gedagte dat hoe minder afskeiding, hoe beter. As daar baie van hulle is, is die teks raserig. Selfs aanhalingstekens skep geraas as dit te dikwels gebruik word.
Kiekies. Stem saam met die span in watter gevalle skermkiekies nodig is. Dit is beslis nie nodig om elke stap te illustreer nie. 'n Groot aantal skermkiekies, inkl. aparte knoppies, inmeng met persepsie, bederf die uitleg. Bepaal die grootte, sowel as die formaat van hoogtepunte en handtekeninge op skermkiekies, en teken dit in die regulasies aan. Onthou dat illustrasies altyd moet ooreenstem met wat geskryf is en relevant moet wees. Weereens, as die produk gereeld opgedateer word, sal dit moeilik wees om tred te hou met almal.
Tekslengte. Vermy te lang artikels. Breek hulle in dele op, en as dit nie moontlik is nie, voeg inhoud met ankerskakels by die begin van die artikel. 'n Eenvoudige manier om 'n artikel visueel korter te maak, is om tegniese besonderhede wat deur 'n nou kring lesers benodig word onder 'n bederf weg te steek.
formate. Kombineer verskeie formate in jou artikels: teks, video en beelde. Dit sal die persepsie verbeter.
Moenie probleme met pragtige uitleg probeer toesmeer nie. Eerlik, ons het self gehoop dat die "omhulsel" die verouderde dokumentasie sou red - dit het nie uitgewerk nie. Die tekste het soveel visuele geraas en onnodige besonderhede bevat dat die regulasies en nuwe ontwerp kragteloos was.
Baie van die bogenoemde sal bepaal word deur die platform wat jy vir dokumentasie gebruik. Ons het byvoorbeeld Confluence. Ek moes ook met hom peuter. As jy belangstel, lees die storie van ons webontwikkelaar: .
Waar om te begin verbeter en hoe om te oorleef
As jou dokumentasie so groot soos ISP-stelsel s'n is en jy nie weet waar om te begin nie, begin met die grootste probleme. Kliënte verstaan nie die dokument nie – verbeter die tekste, maak regulasies, lei skrywers op. Dokumentasie is verouderd - sorg vir interne prosesse. Begin met die gewildste artikels oor die gewildste produkte: vra ondersteuning, kyk na werfontledings en navrae in soekenjins.
Kom ons sê dadelik – dit sal nie maklik wees nie. En dit is ook onwaarskynlik dat dit vinnig sal werk. Tensy jy net begin en dadelik die regte ding doen. Een ding wat ons verseker weet, is dat dit mettertyd beter sal word. Maar die proses sal nooit eindig nie :-).
Bron: will.com