Kuinka valita sivustolle sopivimmat lisäosat, osa 3: Dokumentaatio, artikkelin käännös

Alkuperäinen artikkeli löytyy osoitteesta magazine.joomla.org/issues/issue-aug-2013/item/146...extension-part-3-documentation

Kuinka valita sivustolle sopivimmat lisäosat, osa 3: Dokumentaatio

Joko se on tämän aika taas? Artikkeleita kirjoittaessa aika katoaa, ja ne saadaan valmiiksi aina viime hetkellä. Sama pätee varmaankin myös ihmisiin, jotka kirjoittavat dokumentaatiota lisäosiinsa. Monet meistä käyttäjistä katsovat vain esittelyversion ja lyhyen kuvauksen, jonka jälkeen lataamme ja asennamme tuotteen… mutta mitäpä jos antaisin joitakin syitä, miksi meidän tulisi lisätä dokumentaation lukeminen osaksi tuota tarkastelua….

Viime kerralla puhuimme lisäosalle tarjotusta tuesta, tällä kertaa tutkailemme lisäosan dokumentaation tasoa, joka saatetaan laskea osaksi kehittäjän lisäosalleen tarjoamaa tukea. Jos lisäosa löytyi hyvältä kehittäjältä, on siinä dokumentaatio tarjolla! Se ei välttämättä tarkoita, että lisäosat ilman dokumentaatiota olisivat välttämättä huonoja, dokumentaatio vain saattaa olla hyvin avuliasta.

Kuinka? Asennus, asetuksien säätö, ongelmanratkonta, ylimääräiset kentät ja käytökset yms. löytyvät kaikki hyvästä dokumentaatiosta.

RTFM…

Joskus emme ”muista” lukea 100-sivuista sanakirjaa, jonka joku on kirjoittanut. Emme ehkä halua lukea sitä, mutta meidän tulisi.

Kehittäjien tarkoitus dokumentaatiota tehdessä on lähinnä näyttää käyttäjille, kuinka lisäosaa käytetään, mitä mahdollisuuksia se tarjoaa ja kuinka se otetaan käyttöön. Joskus kuitenkin käy niin, että dokumentaatio ei pysy mukana lisäosan version kanssa ja päädytään tilanteeseen missä esimerkiksi lisäosa on jo versiossa 3, kun dokumentaatio on versiolle 2. Tämä on nähdäkseni ihan ymmärrettävää, kehittäjän on joskus pakko julkaista uusi versio lisäosasta bugin korjaamisen tai ominaisuuden lisäämisen takia, eikä hänellä ole aikaa välittömästi päivittää dokumentaatiota. Tämä ei ole suuren suuri asia, sillä yleensä versiot eivät eroa toisistaan mainittavasti.

Hyvän dokumentaation tulisi sisältää ainakin neljä osaa: Asennus (installation), asetuksien säätäminen (configuration), muokkaaminen (customization) ja ongelmanratkonta (troubleshooting).

Asennus. Tämän sisältö on varsin ilmiselvää. Ihmiset, jotka luulevat että Lisäosien hallinnan kautta suoritettu asennus on kaikki mitä tarvitaan, kokevat karvaan pettymyksen. Joskus on tarpeen lisätä, ottaa käyttöön tai ottaa pois käytöstä liitännäisiä, vaihdella joitakin käytössä olevan palvelimen tai php:n asetuksia yms. Perustason lisäosien kanssa näistä ei pahemmin tarvitse murehtia, mutta jos haluaa lisätä kovemman luokan J!-temppuja sivustolleen saattavat ne tulla tarpeeseen. Itselläni oli ongelmia tämän kanssa joskus, ja sen jälkeen olen lopettanut huonosti tai ei lainkaan dokumentoitujen lisäosien käytön.

Miten on asetuksien säätämisen laita? Tämä riippuu täysin lisäosan ominaisuuksista. Yksinkertainen uutisnäyttö sisältää paljon vähemmän dokumentaatiota asetusten suhteen kuin tilaajajärjestelmälisäosa, jolla on paljon ominaisuuksia kuten uutiskirje, maksut, automaattinen tilauksen uusiminen, käyttäjäryhmät jne. Hyvä käyttöohje kattaa asetuksien kaikki kohdat. Se saattaa venähtää parikymmentä sivua pidemmäksi, mutta parempi lukea vähän lisää kuin päätyä repimään hiuksia päästään. Vaikka käyttäjä ei tarvitsisikaan kaikkia ominaisuuksia, kannattaa ne silti käydä läpi, koska koskaan saattaa törmätä ominaisuuteen, jota kohta tarvitsee, tai jonka olemassaolosta ei edes ollut tietoinen.

Muokkaaminen riippuu täysin käytössä olevasta lisäosasta, joitakin lisäosia ei voida muokata lainkaan (paitsi ylikirjoituksen avulla). Jos siinä kuitenkin muokkausmahdollisuus on, tämän osion pitäisi olla hyvin avulias. Rakentaessani tilauspohjaista sivustoa antoi käyttöohje minulle kaiken tarvitsemani tiedon lisäosan muokkaamiseen. Hyvä dokumentaatio pelasti kehittäjän minun ’häirinnältäni’.

Viimeisenä, vaan ei vähäisimpänä listallamme on ongelmanratkaisu. Hyvän dokumentaation tulisi kattaa ongelmanratkonnasta valtaosa, tosin kaikkea sen on mahdotonta sisältää, koska silloin teknistä tukea ei tarvittaisi lainkaan, eihän? Ongelmat, jotka ilmenevät suhteellisen usein, ja jotka voidaan aina ratkaista samalla tavalla, tulisi aina lisätä tähän osioon. Jos me käyttäjät taas teemme jotain väärin, pitää meidän lähettää tiketti (tukipyyntö), koska ongelma ei ole yleistä tasoa.

Hyvä dokumentaatio voi auttaa meitä paljon, mutta sen tarjoaminen on kehittäjän päätös. Jos kehittäjä on sellaisen tarjonnut, tulisi käyttäjien se lukea. Lyhenne RTFM (Read the F manual) ei ole tuulesta tempaistu.