Ohjelmistodokumentaatio on vain joukko artikkeleita. Mutta jopa ne voivat saada sinut hulluksi. Ensinnäkin vietät pitkän aikaa tarvittavien ohjeiden etsimiseen. Sitten ymmärrät epämääräisen tekstin. Teet kuten kirjoitit, mutta ongelma ei ratkea. Etsit toista artikkelia, hermostut... Tuntia myöhemmin annat periksi kaikesta ja lähdet. Näin huono dokumentointi toimii. Mikä tekee siitä tällaisen ja miten se korjataan - lue leikkauksen alta.
Vanhassa dokumentaatiossamme oli monia puutteita. Olemme työstäneet sitä nyt lähes vuoden ajan, jotta yllä kuvattu skenaario ei vaikuta asiakkaisiimme. Katso, и .
Ongelma 1: Epäselvät, huonosti kirjoitetut artikkelit
Jos dokumentaatiota on mahdotonta ymmärtää, mitä järkeä siinä on? Mutta kukaan ei kirjoita käsittämättömiä artikkeleita tarkoituksella. Niitä tapahtuu, kun kirjoittaja ei ajattele yleisöä ja tarkoitusta, kaataa vettä eikä tarkista tekstiä virheiden varalta.
- Yleisö. Ennen kuin kirjoitat artikkelin, sinun on mietittävä lukijan valmistautumistasoa. On loogista, että aloittelijalle tarkoitetussa artikkelissa sinun ei pidä jättää väliin perusvaiheita ja jättää teknisiä termejä selittämättä, mutta artikkelissa harvinaisesta ominaisuudesta, jota vain ammattilaiset tarvitsevat, sinun tulee selittää sanan PHP merkitys.
- Tavoite. Vielä yksi asia, joka kannattaa miettiä etukäteen. Kirjoittajan on asetettava selkeä tavoite, määritettävä artikkelin hyödyllinen vaikutus ja päätettävä, mitä lukija tekee sen luettuaan. Jos tätä ei tehdä, päädyt kuvaukseen kuvauksen vuoksi.
- Vesi ja hyönteiset. Siellä on paljon turhaa tietoa ja byrokratiaa, virheet ja kirjoitusvirheet häiritsevät käsitystä. Vaikka lukija ei olisikaan kieliopin natsi, huolimattomuus tekstissä voi sammuttaa hänet.
Harkitse yllä olevia vinkkejä, ja artikkelit tulevat selkeämmiksi - taatusti. Jos haluat tehdä siitä vielä paremman, käytä meidän .
Ongelma 2. Artikkelit eivät vastaa kaikkiin kysymyksiin
On huono asia, kun dokumentaatio ei pysy kehityksen mukana, ei vastaa oikeisiin kysymyksiin ja siinä olevia virheitä ei korjata vuosiin. Nämä eivät ole niinkään tekijän ongelmia, vaan prosessien organisointia yrityksen sisällä.
Dokumentaatio ei pysy kehityksen mukana
Ominaisuus on jo julkaisussa, markkinointi aikoo kattaa sen, ja sitten käy ilmi, että uutta artikkelia tai käännöstä ei vieläkään ole dokumentaatiossa. Jouduimme jopa lykkäämään julkaisua tämän takia. Voit pyytää kaikkia luovuttamaan tehtäviä teknisille kirjoittajille ajoissa niin paljon kuin haluat, mutta se ei toimi. Jos prosessia ei ole automatisoitu, tilanne toistaa itseään.
Olemme tehneet muutoksia YouTrackiin. Uudesta ominaisuudesta artikkelin kirjoittaminen jää tekniselle kirjoittajalle samalla hetkellä, kun ominaisuutta aletaan testata. Sitten markkinointi oppii siitä valmistautuakseen edistämiseen. Ilmoitukset tulevat myös Mattermostin yritysviestintään, joten on yksinkertaisesti mahdotonta jäädä paitsi kehittäjien uutisista.
Dokumentaatio ei vastaa käyttäjien pyyntöjä
Olemme tottuneet työskentelemään näin: ominaisuus ilmestyi, me puhuimme siitä. Kuvasimme, kuinka se kytketään päälle, sammutetaan ja tehdään hienosäätöjä. Mutta entä jos asiakas käyttää ohjelmistoamme tavalla, jota emme odottaneet? Vai onko siinä virheitä, joita emme ajatelleet?
Varmistaaksesi, että dokumentaatio on mahdollisimman täydellinen, suosittelemme tukipyyntöjen, temaattisten foorumien kysymysten ja hakukoneiden kyselyjen analysointia. Suosituimmat aiheet siirretään teknisille kirjoittajille, jotta he voivat täydentää olemassa olevia artikkeleita tai kirjoittaa uusia.
Dokumentaatiota ei paranneta
Sitä on vaikea tehdä täydellisesti heti, virheitä tulee silti. Voit toivoa asiakkailta palautetta, mutta on epätodennäköistä, että he raportoivat jokaisesta kirjoitusvirheestä, epätarkkuudesta, käsittämättömästä tai perusteettomasta artikkelista. Asiakkaiden lisäksi työntekijät lukevat dokumentaatiota, mikä tarkoittaa, että he näkevät samat virheet. Tätä saa käyttää! Sinun on vain luotava olosuhteet, joissa on helppo ilmoittaa ongelmasta.
Meillä on sisäisessä portaalissa ryhmä, johon työntekijät jättävät kommentteja, ehdotuksia ja ideoita dokumentaatiosta. Tarvitseeko tuki artikkelin, mutta sitä ei ole olemassa? Huomasiko testaaja epätarkkuuden? Onko kumppani valittanut kehitysjohtajille virheistä? Kaikki tässä ryhmässä! Tekniset kirjoittajat korjaavat jotkin asiat heti, siirtävät osan YouTrackiin ja antavat toisille aikaa miettiä. Jotta aihe ei lamaannu, muistutamme silloin tällöin ryhmän olemassaolosta ja palautteen tärkeydestä.
Ongelma 3. Oikean artikkelin löytäminen kestää kauan.
Artikkeli, jota ei löydy, ei ole parempi kuin artikkeli, jota ei löydy. Hyvän dokumentaation mottona tulisi olla "Helppo etsiä, helppo löytää". Miten tämä saavutetaan?
Järjestä rakenne ja määritä aiheiden valintaperiaate. Rakenteen tulee olla mahdollisimman läpinäkyvä, jotta lukija ei ajattele: "Mistä löydän tämän artikkelin?" Yhteenvetona voidaan todeta, että on kaksi lähestymistapaa: käyttöliittymästä ja tehtävistä.
- Käyttöliittymästä. Sisältö kopioi paneelin osiot. Näin oli vanhassa ISP-järjestelmän dokumentaatiossa.
- Tehtävistä. Artikkelien ja osioiden otsikot kuvastavat käyttäjien tehtäviä; Otsikot sisältävät melkein aina verbejä ja vastauksia "miten"-kysymykseen. Nyt ollaan siirtymässä tähän muotoon.
Minkä tahansa lähestymistavan valitsetkin, varmista, että aihe liittyy siihen, mitä käyttäjät etsivät, ja että se on käsitelty tavalla, joka vastaa käyttäjän kysymykseen.
Määritä keskitetty haku. Ihanteellisessa maailmassa haun pitäisi toimia, vaikka kirjoitat väärin tai teet virheen kielen kanssa. Hakumme Confluencessa ei voi miellyttää meitä tällä. Jos sinulla on useita tuotteita ja dokumentaatio on yleistä, räätälöi haku sen sivun mukaan, jolla käyttäjä on. Meidän tapauksessamme pääsivun haku toimii kaikille tuotteille, ja jos olet jo tietyssä osiossa, niin vain siinä oleville artikkeleille.
Lisää sisältöä ja korppujauhoja. On hyvä, kun jokaisella sivulla on valikko ja vaihemerkit – käyttäjän polku nykyiselle sivulle ja mahdollisuus palata mille tahansa tasolle. Vanhassa ISP-järjestelmän dokumentaatiossa sinun oli poistuttava artikkelista päästäksesi sisältöön. Se oli epämukavaa, joten korjasimme sen uudessa.
Sijoita linkit tuotteeseen. Jos ihmiset tulevat tukemaan yhä uudelleen samalla kysymyksellä, on järkevää lisätä vihje sen ratkaisuun käyttöliittymään. Jos sinulla on tietoja tai käsitystä siitä, milloin käyttäjällä on ongelmia, voit myös ilmoittaa heille postituslistalla. Osoita heille huolta ja ota taakka pois tuesta.
Ponnahdusikkunan oikealla puolella on linkki artikkeliin DNSSEC:n määrittämisestä ISPmanagerin verkkotunnuksen hallintaosiossa.
Aseta ristiviittaukset dokumentaatioon. Artikkelit, jotka liittyvät toisiinsa, tulee "linkittää". Jos artikkelit ovat peräkkäisiä, muista lisätä eteenpäin- ja taaksepäin osoittavat nuolet jokaisen tekstin loppuun.
Todennäköisesti henkilö etsii ensin vastausta kysymykseensä ei sinulle, vaan hakukoneelle. On sääli, jos siellä ei ole teknisistä syistä linkkejä dokumentaatioon. Huolehdi siis hakukoneoptimoinnista.
Ongelma 4. Vanhentunut asettelu häiritsee havaintoa
Huonojen tekstien lisäksi suunnittelu voi pilata dokumentaatiota. Ihmiset ovat tottuneet lukemaan hyvin kirjoitettua materiaalia. Blogit, sosiaaliset verkostot, media - kaikki sisältö ei ole vain kaunista, vaan myös helppolukuista ja silmää miellyttävää. Siksi voit helposti ymmärtää tekstiä näkevän henkilön tuskan, kuten alla olevassa kuvakaappauksessa.
Tässä artikkelissa on niin paljon kuvakaappauksia ja kohokohtia, että ne eivät auta, vaan vain häiritsevät havaintoa (kuvaa voi napsauttaa)
Dokumentaatiosta ei kannata tehdä pitkiä efektejä, mutta perussäännöt on otettava huomioon.
Layout. Määritä leipätekstin leveys, fontti, koko, otsikot ja täyte. Palkkaa suunnittelija ja hyväksy työ tai tee se itse lukemalla Artjom Gorbunovin kirja "Typografia ja taitto". Se esittää vain yhden näkymän asettelusta, mutta se on aivan riittävä.
valinta. Selvitä, mitä tekstissä on korostettava. Tyypillisesti tämä on polku käyttöliittymässä, painikkeissa, koodinlisäyksissä, konfiguraatiotiedostoissa, "Please note" -lohkoissa. Määritä näiden elementtien jako ja kirjaa ne sääntöihin. Muista, että mitä vähemmän vuotoa, sitä parempi. Kun niitä on paljon, teksti on meluisaa. Jopa lainausmerkit aiheuttavat melua, jos niitä käytetään liian usein.
kuvakaappauksia. Sovi tiimin kanssa, missä tapauksissa kuvakaappauksia tarvitaan. Jokaista vaihetta ei todellakaan tarvitse havainnollistaa. Suuri määrä kuvakaappauksia, mm. erilliset painikkeet, häiritsevät havaintoa, pilaavat asettelun. Määritä kuvakaappausten kohokohtien ja allekirjoitusten koko sekä muoto ja kirjaa ne sääntöihin. Muista, että kuvien tulee aina vastata kirjoitettua ja olla relevantteja. Jälleen, jos tuotetta päivitetään säännöllisesti, on vaikea seurata kaikkia.
Tekstin pituus. Vältä liian pitkiä artikkeleita. Jaa ne osiin ja jos tämä ei ole mahdollista, lisää sisältöä ankkurilinkeillä artikkelin alkuun. Yksinkertainen tapa lyhentää artikkelia visuaalisesti on piilottaa spoilerin alle kapean lukijapiirin tarvitsemat tekniset yksityiskohdat.
Форматы. Yhdistä artikkeleissasi useita muotoja: tekstiä, videoita ja kuvia. Tämä parantaa käsitystä.
Älä yritä peitellä ongelmia kauniilla asetteluilla. Rehellisesti sanottuna toivoimme itse, että "kääre" pelastaisi vanhentuneet asiakirjat - se ei toiminut. Tekstit sisälsivät niin paljon visuaalista melua ja tarpeettomia yksityiskohtia, että määräykset ja uusi muotoilu olivat voimattomia.
Suurin osa yllä olevista määräytyy dokumentointiin käyttämäsi alustan mukaan. Meillä on esimerkiksi Confluence. Minunkin piti puuhailla hänen kanssaan. Jos olet kiinnostunut, lue verkkokehittäjämme tarina: .
Mistä aloittaa parantaminen ja kuinka selviytyä
Jos dokumentaatiosi on yhtä laaja kuin ISPsystemin, etkä tiedä mistä aloittaa, aloita suurimmista ongelmista. Asiakkaat eivät ymmärrä dokumenttia - paranna tekstejä, säädä, kouluta kirjoittajia. Dokumentaatio on vanhentunut - huolehdi sisäisistä prosesseista. Aloita suosituimmista tuotteista suosituimmista artikkeleista: pyydä tukea, katso sivuston analytiikkaa ja kyselyitä hakukoneissa.
Sanotaan heti – se ei tule olemaan helppoa. Eikä sekään todennäköisesti onnistu nopeasti. Ellet ole vasta aloittamassa ja tee oikeaa asiaa heti. Yksi asia, jonka tiedämme varmasti, on, että se paranee ajan myötä. Mutta prosessi ei lopu koskaan :-).
Lähde: will.com