Softwaredokumintaasje is gewoan in set fan artikels. Mar sels se kinne jo gek meitsje. Earst besteegje jo in lange tiid op syk nei de nedige ynstruksjes. Dan begripe jo de obskure tekst. Jo dogge lykas skreaun, mar it probleem is net oplost. Jo sykje in oar artikel, jo wurde senuweftich... In oere letter jouwe jo alles op en geane fuort. Dit is hoe min dokumintaasje wurket. Wat makket it sa en hoe't jo it reparearje - lês ûnder de besuniging.
Der wiene in protte tekoartkommingen yn ús âlde dokumintaasje. Wy hawwe it no hast in jier ferwurke, sadat it hjirboppe beskreaune senario gjin ynfloed hat op ús kliïnten. Sjen, и .
Probleem 1: Undúdlike, min skreaune artikels
As de dokumintaasje ûnmooglik is te begripen, wat is it punt derfan? Mar gjinien skriuwt ûnbegryplike artikels mei opsetsin. Se barre as de skriuwer net tinkt oer it publyk en doel, giet wetter en kontrolearret de tekst net op flaters.
- It publyk. Foardat jo in artikel skriuwe, moatte jo tinke oer it tariedingsnivo fan 'e lêzer. It is logysk dat jo yn in artikel foar in begjinner gjin basisstappen oerslaan en technyske termen sûnder útlis litte, mar yn in artikel oer in seldsume funksje dy't allinich professionals nedich binne, moatte jo de betsjutting fan it wurd PHP net útlizze.
- Goal. Noch ien ding om fan tefoaren oer te tinken. De skriuwer moat in dúdlik doel ynstelle, it nuttige effekt fan it artikel bepale, en beslute wat de lêzer sil dwaan nei it lêzen. As dit net dien wurdt, sille jo einigje mei beskriuwing foar de beskriuwing.
- Wetter en bugs. Der is in soad oerstallige ynformaasje en burokrasy, flaters en typfouten bemuoie mei de waarnimming. Sels as de lêzer gjin grammatikanazi is, kin achtleazens yn 'e tekst him útsette.
Beskôgje de tips hjirboppe, en de artikels sille dúdliker wurde - garandearre. Om it noch better te meitsjen, brûk ús .
Probleem 2. Artikels beantwurdzje net alle fragen
It is slim as de dokumintaasje net byhâldt mei ûntwikkeling, gjin echte fragen beantwurdet en flaters dêryn jierrenlang net korrizjearre wurde. Dit binne problemen net sasear fan de skriuwer, mar fan de organisaasje fan prosessen binnen it bedriuw.
Dokumintaasje hâldt net by mei ûntwikkeling
De funksje is al yn release, marketing is fan plan om it te dekken, en dan docht bliken dat it nije artikel of oersetting noch net yn 'e dokumintaasje is. Wy moasten sels de frijlitting hjirtroch útstelle. Jo kinne elkenien freegje om op 'e tiid taken oer te jaan oan technyske skriuwers safolle jo wolle, mar it sil net wurkje. As it proses net automatisearre is, sil de situaasje himsels werhelje.
Wy hawwe feroarings makke oan YouTrack. De taak om in artikel te skriuwen oer in nije funksje falt op de technyske skriuwer op itselde momint as de funksje begjint te testen. Dan leart marketing deroer om foar te bereiden op promoasje. Notifikaasjes komme ek nei de Mattermost bedriuwsmessenger, dus it is gewoan ûnmooglik om nijs fan ûntwikkelders te missen.
Dokumintaasje wjerspegelet gjin fersiken fan brûkers
Wy binne wend om sa te wurkjen: der kaam in funksje út, wy prate der oer. Wy beskreaun hoe't jo it ynskeakelje, it útsette en fyn oanpassingen meitsje. Mar wat as in klant ús software brûkt op in manier dy't wy net ferwachte hawwe? Of hat it flaters dêr't wy net oer neitocht hawwe?
Om te soargjen dat de dokumintaasje sa folslein mooglik is, advisearje wy it analysearjen fan stipefersiken, fragen oer tematyske foarums en fragen yn sykmasines. De populêrste ûnderwerpen wurde oerdroegen oan technyske skriuwers, sadat se besteande artikels kinne oanfolje of nije kinne skriuwe.
Dokumintaasje wurdt net ferbettere
It is lestich om it direkt perfekt te dwaan; d'r sille noch flaters wêze. Jo kinne hoopje op feedback fan klanten, mar it is net wierskynlik dat se elke typflater, unakkuraatheid, ûnbegryplik of net fûn artikel sille melde. Neist kliïnten lêze meiwurkers de dokumintaasje, wat betsjut dat se deselde flaters sjogge. Dit kin brûkt wurde! Jo moatte gewoan betingsten meitsje wêryn it maklik wêze sil om in probleem te melden.
Wy hawwe in groep op de ynterne portal dêr't meiwurkers litte opmerkings, suggestjes en ideeën op dokumintaasje. Hat stipe in artikel nedich, mar it bestiet net? Hat de tester de ûnkrektens opmurken? Hat de partner klage by ûntwikkelingsbehearders oer flaters? Allegear yn dizze groep! Technyske skriuwers reparearje guon dingen direkt, drage guon dingen oer nei YouTrack, en jouwe oaren wat tiid om oer te tinken. Om foar te kommen dat it ûnderwerp ferdwynt, herinnerje wy jo sa no en dan oan it bestean fan de groep en it belang fan feedback.
Probleem 3. It duorret lang om it goede artikel te finen.
In artikel dat net te finen is is net better as in artikel dat net te finen is. It motto fan goede dokumintaasje moat wêze "Easy to search, easy to find." Hoe dit te berikken?
Organisearje de struktuer en bepale it prinsipe foar it kiezen fan ûnderwerpen. De struktuer moat sa transparant mooglik wêze, sadat de lêzer net tinkt: "Wêr kin ik dit artikel fine?" Om gearfetsje, binne d'r twa oanpakken: fan 'e ynterface en fan' e taken.
- Ut de ynterface. De ynhâld duplikearret de panielseksjes. Dit wie it gefal yn 'e âlde ISPsystem dokumintaasje.
- Fan taken. De titels fan artikels en seksjes wjerspegelje de taken fan de brûkers; Titels befetsje hast altyd tiidwurden en antwurden op de "hoe" fraach. No geane wy nei dit formaat.
Watfoar oanpak jo ek kieze, soargje derfoar dat it ûnderwerp relevant is foar wat brûkers sykje en wurdt behannele op in manier dy't spesifyk de fraach fan 'e brûker oanpakt.
Stel in sintralisearre sykopdracht op. Yn in ideale wrâld soe sykjen wurkje moatte, sels as jo ferkeard staverje of in flater meitsje mei de taal. Us sykjen yn Confluence oant no ta kin ús hjirmei net befredigje. As jo in protte produkten hawwe en de dokumintaasje is algemien, oanpasse de sykopdracht oan 'e side wêrop de brûker is. Yn ús gefal wurket it sykjen op 'e haadside foar alle produkten, en as jo al yn in spesifike seksje binne, dan allinich foar de artikels dêryn.
Foegje ynhâld en breadcrumbs ta. It is goed as elke side in menu en breadcrumbs hat - it paad fan 'e brûker nei de hjoeddeistige side mei de mooglikheid om werom te gean nei elk nivo. Yn 'e âlde ISPsystem-dokumintaasje moasten jo it artikel ferlitte om by de ynhâld te kommen. It wie ûngemaklik, dat wy reparearren it yn 'e nije.
Plak keppelings yn it produkt. As minsken komme om hieltyd wer te stypjen mei deselde fraach, is it logysk om in hint te foegjen mei syn oplossing foar de ynterface. As jo gegevens of ynsjoch hawwe yn wannear't in brûker in probleem ûnderfynt, kinne jo har ek ynformearje mei in ferstjoerlist. Lit har soarch sjen en nim de lêst fan stipe.
Oan de rjochterkant yn it pop-up finster is in keppeling nei in artikel oer it ynstellen fan DNSSEC yn de domein behear seksje fan ISPmanager
Stel krúsferwizings yn yn dokumintaasje. Artikels dy't mei-inoar besibbe binne moatte "keppele wurde". As de artikels sekwinsjele binne, wês dan wis dat jo pylken foarút en efterút tafoegje oan 'e ein fan elke tekst.
Meast wierskynlik, in persoan sil earst gean op syk nei in antwurd op syn fraach net oan jo, mar nei in sykmasine. It is spitich as der om technyske redenen gjin keppelings binne nei de dokumintaasje. Soarch dus foar sykmasino-optimisaasje.
Probleem 4. Ferâldere yndieling bemuoit mei waarnimming
Neist minne teksten kin dokumintaasje bedoarn wurde troch ûntwerp. Minsken binne wend om goed skreaun materiaal te lêzen. Blogs, sosjale netwurken, media - alle ynhâld wurdt presintearre net allinnich moai, mar ek maklik te lêzen en noflik foar it each. Dêrom kinne jo de pine maklik begripe fan in persoan dy't tekst sjocht lykas yn 'e skermôfbylding hjirûnder.
D'r binne safolle skermôfbyldings en hichtepunten yn dit artikel dat se net helpe, mar allinich ynterferearje mei waarnimming (de foto is te klikken)
Jo moatte gjin lange lêzing meitsje fan 'e dokumintaasje mei in boskje effekten, mar jo moatte rekken hâlde mei de basisregels.
Opmaak. Bepale lichemstekstbreedte, lettertype, grutte, kopteksten en padding. Hiere in ûntwerper, en om it wurk te akseptearjen of it sels te dwaan, lês it boek fan Artyom Gorbunov "Typografy en yndieling." It presintearret mar ien werjefte fan 'e yndieling, mar it is genôch genôch.
Allocations. Bepale wat fereasket klam yn 'e tekst. Typysk is dit in paad yn 'e ynterface, knoppen, koade-ynfoegingen, konfiguraasjebestannen, "Tink derom" blokken. Bepale wat de allocaasjes fan dizze eleminten sille wêze en registrearje se yn 'e regeljouwing. Hâld der rekken mei dat hoe minder ûntslach, hoe better. As der in protte binne, is de tekst lawaaierich. Sels oanhalingstekens meitsje lûd as se te faak brûkt wurde.
Screenshots. Iens mei it team yn hokker gefallen screenshots binne nedich. It is perfoarst net nedich om elke stap te yllustrearjen. In grut oantal skermôfbyldings, ynkl. aparte knoppen, interfere mei persepsje, bedjerre de yndieling. Bepale de grutte, lykas it formaat fan hichtepunten en hantekeningen op skermôfbyldings, en registrearje se yn 'e regeljouwing. Unthâld dat yllustraasjes altyd oerienkomme moatte mei wat skreaun is en relevant wêze moatte. Nochris, as it produkt regelmjittich bywurke wurdt, sil it lestich wêze om elkenien by te hâlden.
Tekst lingte. Foarkom te lange artikels. Brek se yn dielen, en as dit net mooglik is, foegje dan ynhâld ta mei ankerkeppelings oan it begjin fan it artikel. In ienfâldige manier om in artikel visueel koarter te meitsjen is technyske details te ferbergjen dy't nedich binne troch in smelle sirkel fan lêzers ûnder in spoiler.
Formaten. Kombinearje ferskate formaten yn jo artikels: tekst, fideo en ôfbyldings. Dit sil de persepsje ferbetterje.
Besykje net problemen te dekken mei prachtige yndieling. Earlik sein, wy sels hope dat de "wrapper" soe bewarje de ferâldere dokumintaasje - it slagge net. De teksten befette safolle fisueel lûd en ûnnedige details dat de regeljouwing en it nije ûntwerp machteleas wiene.
In protte fan it boppesteande sil wurde bepaald troch it platfoarm dat jo brûke foar dokumintaasje. Bygelyks, wy hawwe Confluence. Ik moast ek mei him tintsje. As jo ynteressearre binne, lês it ferhaal fan ús webûntwikkelder: .
Wêr begjinne te ferbetterjen en hoe te oerlibjen
As jo dokumintaasje sa grut is as ISPsystem's en jo net witte wêr't jo moatte begjinne, begjin dan mei de grutste problemen. Klanten begripe it dokumint net - ferbetterje de teksten, meitsje regeljouwing, traine skriuwers. Dokumintaasje is ferâldere - soargje foar ynterne prosessen. Begjin mei de populêrste artikels oer de populêrste produkten: freegje stipe, besjoch side-analytyk en fragen yn sykmasines.
Litte wy daliks sizze - it sil net maklik wêze. En it is ek net wierskynlik om fluch te wurkjen. Behalven as jo gewoan begjinne en it goede ding direkt dwaan. Ien ding dat wy wis witte is dat it mei de tiid better wurde sil. Mar it proses sil nea einigje :-).
Boarne: www.habr.com