Tarkvara dokumentatsioon on lihtsalt artiklite kogum. Kuid isegi need võivad olla tüütu. Alguses otsid kaua vajalikke juhiseid. Siis püüad aru saada arusaamatust tekstist. Tegutsed nagu on kirjutatud, aga probleem ei lahene. Otsid teist artiklit, ärritute... Tunni aja pärast loobud kõikest ja lahkud. Nii töötab halb dokumentatsioon. Miks see nii on ja kuidas seda parandada — loe edasi.
Meie vanas dokumentatsioonis oli palju puuduseid. Juba peaaegu aasta oleme seda töötanud, et eespool kirjeldatud stsenaarium ei mõjutaks meie kliente. Vaata, ja .
Probleem 1. Arusaamatud, halvasti kirjutatud artiklid
Kui dokumentatsioonis ei saa aru, milline on selle mõte? Kuid keegi ei kirjuta arusaamatuid artikleid spetsiaalselt. Need tekivad, kui autor ei mõtle publikule ja eesmärgile, kirjutab liigseid detaile ja ei kontrolli teksti vigade osas.
- Publik. Enne artikli kirjutamist tuleks mõelda lugeja ettevalmistustasemele. On loogiline, et algajatele suunatud artiklis ei tasu jätta vahele põhietappe ega kasutada tehnilisi termineid seletamata, samas kui haruldase funktsiooni, mida vajavad vaid professionaalid, puhul tuleks sõna PHP tähendust põhjalikult selgitada.
- Eesmärk. Veel üks asi, millele on parem eelnevalt mõelda. Autor peaks seadma selge eesmärgi, määratlema artikli kasuliku tegevuse ja otsustama, mida lugeja pärast selle lugemist teeb. Kui seda ei tehta, jääb jutt ainult jutu pärast.
- Vesi ja vead. Liigne informatsioon ja bürokraatia, vead ja trükivead takistavad arusaamist. Ieven kui lugeja ei ole grammatikanaats, võib tekstis hooletus teda eemale tõukata.
Kasutage ülaltoodud näpunäiteid ja artiklid saavad selgemaks - garanteeritud. Selle veelgi paremaks muutmiseks, võtke kasutusele meie .
Probleem 2. Artiklid ei vasta kõigile küsimustele
Halb on, kui dokumentatsioon ei järgi arendust, ei vasta tegelikele küsimustele ja vead jäävad seal mitmeks aastaks parandamata. Need on probleemid, mis ei ole niivõrd autori, vaid ettevõtte siseste protsesside küsimus.
Dokumentatsioon ei järgi arendust
Funktsioon on juba välja antud, turundus kavatseb selle kohta teavet jagada, kuid selgub, et dokumentatsioonis pole veel uut artiklit või tõlget. Selle tõttu oleme isegi pidanud väljaannet edasi lükkama. Saame nii palju kui tahes paluda kõigil õigel ajal ülesanne tehnilistele kirjanikele edastada, kuid see ei toimi. Kui protsessi ei automatiseerita, kordub olukord.
Oleme teinud muudatusi YouTrackis. Uue funktsiooni artikli kirjutamise ülesanne langeb tehnilise kirjaniku toimetusse just siis, kui võimalusi hakatakse katsetama. Sel hetkel saab sellest teada ka turundus, et valmistuda reklaamimiseks. Teated tulevad ka ettevõtte sisemisse suhtlusrakendusse Mattermost, nii et arendajatelt uudiseid lihtsalt ei saa vahele jätta.
Dokumentatsioon ei kajasta kasutajate vajadusi
Oleme harjunud töötama nii: funktsioon on välja antud, siis räägime sellest. Kirjeldame, kuidas seda sisse ja välja lülitada, teha peeneid seadistusi. Aga mis juhtub, kui klient kasutab meie tarkvara viisil, mida me ei ole ette näinud? Või kui tal tekivad vead, millele me ei ole mõelnud?
Dokumendi maksimaalse täpsuse tagamiseks soovitame analüüsida tugiteenuste päringuid, teemasid foorumites ja otsingupäringute soovitusi. Kõige populaarsemad teemad tuleks edastada tehnilise dokumentatsiooni autoritele, et nad saaksid olemasolevaid artikleid täiendada või kirjutada uusi.
Dokumentatsiooni ei arendata edasi
On keeruline saavutada täiuslikkust kohe, vigu ikka esineb. Saame loota klientide tagasisidele, kuid tõenäoliselt ei teata nad igast trükiveast, ebatäpsusest või ebaselgest või leitud artiklist. Lisaks klientidele loevad dokumentatsiooni ka töötajad, mis tähendab, et nad märkavad samu vigu. Seda saab ära kasutada! Peame lihtsalt looma tingimused, kus probleemidest on lihtne teada anda.
Meil on siseportaalis grupp, kus töötajad jätavad märkuseid, ettepanekuid ja ideid dokumentatsiooni osas. Kas toimetusele on vajalik artikkel, aga seda pole? Testija märkis ebatäpsuse? Partner kaebas arendusjuhtidele vigade pärast? Kõik on siin grupis! Tehnilised kirjutajad teevad midagi kohe ära, mõned asjad kantakse YouTracki, mõned võetakse arutlusele. Et teema ei ununeks, tuletame aeg-ajalt meelde grupi olemasolu ja tagasiside tähtsust.
Probleem 3. Vajalikku artiklit peab kaua otsima
Artikkel, mida ei leia, ei ole parem kui artikkel, mida üldse ei ole. Hea dokumentatsiooni moto peaks olema lause „Lihtne otsida, lihtne leida“. Kuidas seda saavutada?
Korrastada struktuur ja määratleda teema valimise printsiip. Struktuur peab olema võimalikult läbipaistev, et lugeja ei mõtleks, „Kus ma saan seda artiklit leida?“. Kui üldistada, siis on olemas kaks lähenemist: kasutajaliidesest ja ülesannetest.
- Kasutajaliidesest. Sisu dubleerib paneeli jaotisi. Nii oli vanas ISPsystemi dokumentatsioonis.
- Kasutajate ülesanded. Artiklite ja sektsioonide nimed peegeldavad kasutajate vajadusi; pealkirjades on peaaegu alati verbe ja vastuseid küsimusele „kuidas teha”. Nüüd liigume sellise formaadi suunas.
Millist lähenemist te ka ei valiks, veenduge, et teema vastab kasutajate päringutele ja on käsitletud viisil, et kasutaja saaks oma küsimusele selgelt vastuse.
Keskse otsingu seadistamine. Ideaaltingimustes peaks otsing toimima isegi siis, kui teete trükivigu või valite vale keele. Meie otsing Confluences seda kahjuks veel ei võimalda. Kui teil on palju tooteid ja dokumentatsioon on ühine, kohandage otsing lehe järgi, kus kasutaja asub. Meie puhul töötab otsing peamiselt kõigi toodete peale ja kui te juba olete konkreetses jaotises, siis ainult selle sektsiooni artiklite leidmiseks.
Lisa sisu ja „leivaosutused”. Igal lehel on hea, kui on menüü ja leivaosutused — kasutaja tee hetke leheni võimalusega taganeda igal tasemel. ISPsystemi vanas dokumentatsioonis pidi artiklist lahkuma, et pääseda sisule. See oli ebamugav, seega oleme uues seda parandanud.
Seada lingid tootesse. Kui inimesed tulevad korduvalt tugiteenusesse sama küsimusega, on mõistlik lisada sellega seotud vihje kasutajaliidesesse. Kui teil on andmed või arusaam, millal kasutaja probleemiga silmitsi seisab, võite teda ka teavitada uudiskirjaga. Nii näitate hoolivust ning vähendate tugikoormust.
Paremal hüpikaknas on link DNSSEC-i seadistamise artiklile ISPmanageri domeeni haldamise jaotises.
Seadistage ristlingid dokumentatsiooni sees.. Artiklid, mis omavahel seotud, peaksid olema 'lingitud'. Kui artiklid on järjestikused, lisage kindlasti iga teksti lõppu nooled edasi ja tagasi.
Tõenäoliselt otsib inimene esmalt vastust oma küsimusele mitte teilt, vaid otsingumootorist. On kahetsusväärne, kui seal ei ole tehnilistel põhjustel linke dokumentatsioonile. Seega hoolitsege otsingumootori optimeerimise eest.
Probleem 4. Ahnud kujundus häirib tajumist.
Halbadest tekstist võib dokumentatsiooni rikuda ka disain. Inimesed on harjunud lugema hästi vormindatud materjale. Blogid, sotsiaalmeedia, meedia — kogu sisu esitatakse mitte ainult ilusana, vaid ka lugemismugavust silmas pidades. Seetõttu on kerge mõista valu, mida tunneb inimene, kes näeb teksti nagu alloleval ekraanipildil.
Selles artiklis on ekraanipilte ja esiletõstmisi nii palju, et need ei aita, vaid segavad arusaamist (pilt on klikitav).
Ärge tehke dokumentatsioonist pikka lugemist, kus on palju efekte, kuid põhireeglid tuleks siiski silmas pidada.
Vormindamine. Määrake põhiteksti laius, font, suurus, pealkirjad ja marginaalid. Kaasake disainer, ja kui soovite tööd vastu võtta või iseseisvalt hakkama saada, lugege Artem Gorbunovi raamatut „Tüpsus ja vormindamine“. Selles on esitatud ainult üks vaatenurk vormindamise kohta, kuid see on täiesti piisav.
Esiletõstmised. Määrake, millised tekstielemendid vajavad rõhutamist. Üldiselt on need liideses, nupud, koodijupid, konfiguratsioonifailid, samuti 'Pange tähele' blokid. Otsustage, kuidas need elemendid esitatakse ja fikseerige see õigusaktides. Pidage meeles, et vähem rõhutusi on paremad. Kui neid on liiga palju, muudab tekst 'müraks'. Müra tekitavad isegi jutumärgid, kui neid kasutatakse liiga sageli.
Ekraanipildid. Leppige meeskonnaga kokku, millal on vajalikud ekraanipildid. Iga sammu illustreerimine pole tingimata vajalik. Suur hulk ekraanipilte, sealhulgas individuaalsed nupud, kahjustavad arusaamist ja rikuvad kujundust. Määrake ekraanipiltide rõhutuste ja pealkirjade suurus ning formaat ning fikseerige see õigusaktides. Pidage meeles, et illustratsioonid peavad alati vastama kirjutatule ja olema ajakohased. Jälle, kui toodet uuendatakse regulaarselt, on igaühe jälgimine keeruline.
Teksti pikkus. Vältige liiga pikki artikleid. Jagage need osadeks, ja kui see ei ole võimalik, lisage artikli algusesse sisu koos ankrulinkidega. Lihtne viis, kuidas muuta artikkel visuaalselt lühemaks, on peita tehnilised üksikasjad, mis on vajalikud kitsale lugejaskonnale, spoilerikasti alla.
Formaadid. Ühendage artiklites mitu formaati: tekst, video ja pildid. See parandab tajumist.
Ärge proovige probleeme ilusate kujundustega varjata. Ausalt öeldes lootsime isegi, et "ümbris" päästab aegunud dokumentatsiooni — aga see ei töötanud. Tekstides oli liiga palju visuaalset müra ja tarbetut teavet, mistõttu uus regulatsioon ja kujundus olid jõuetud.
Palju sellest, mis eespool on kirjeldatud, määrab platvorm, mida kasutate dokumentatsiooniks. Meil on näiteks Confluence. Sellega tuli ka vaeva näha. Kui see huvitab, lugege meie veebiarendaja lugu: .
Kust alustada paranemist ja kuidas ellu jääda
Kui teie dokumentatsioon on sama mahukas kui ISPsystemi oma ja ei tea, kust alustada, keskenduge kõige tõsisematele probleemidele. Klientidele ei ole dokumendid arusaadavad — tegelege tekstide parandamisega, looge reeglid, koolitage kirjanikke. Dokumentatsioon on aegunud — võtke käsile sisemised protsessid. Alustage kõige populaarsematest artiklitest enim nõutud toodete kohta: küsige tugiteenuseks, vaadake veebianalüütikat ja otsingupäringute allikaid.
Ütleme kohe - kerge see ei ole. Ja kiiresti ka tõenäoliselt ei õnnestu. Juhul kui te just alustate ja teete kohe õigesti. Üks asi on kindel — aja jooksul läheb paremaks. Kuid see protsess ei lõppe kunagi :-).
Allikas: habr.com
