Aiemmin kävin läpi keinoja selvittää, kuinka edeltäjäsi käyttivät DoX CMS:ää, jos he eivät jättäneet jälkeensä sisäistä dokumentaatiota aiheesta. Kuten korostin kyseisessä artikkelissa, sisäinen dokumentaatio koskien oikeita käyttötapoja on erittäin tärkeää. Tämä pitää paikkansa kaikkien rakenteisten dokumentointijärjestelmien osalta. Tällä kertaa neuvon, millaisia seikkoja sisäisessä dokumentaatiossa tulee huomioida DoX CMS:n tapauksessa.
Sisäinen dokumentaatio sisältää sekä järjestelmään itseensä tehdyt muistiinpanot ja ohjeistukset että erillisen tyylioppaan kirjoittamisen tueksi. Käyn ensin läpi DoX CMS:n sisäisiä keinoja dokumentoida oikeita käyttötapoja. Sitten keskustelen seikoista, jotka sisäisessä tyylioppaassa täytyy huomioida.
Sisäinen dokumentaatio DoX:issa
DoX CMS:n sisällä käytettävissä olevat keinot kirjata ylös toimintatapoja ja muita muistiinpanoja voi jakaa kolmeen kategoriaan: nimet, kuvaukset ja kommentit. Kuhunkin niistä kuuluu useampia käyttötapoja järjestelmän sisällä.
Nimet
Eri palasien nimet ovat itsessään ilmeinen tapa ilmoittaa, mitä ne tekevät. Toisaalta nimi voi vain auttaa käyttäjiä päättelemään oikean käyttötarkoituksen, joten pelkät kuvaavat nimet eivät riitä. Kaikkia palasia ei voi myöskään nimetä sisäisen dokumentaation tarpeiden mukaisesti. Esimerkiksi otsikkosisältöjen otsikot tulevat julkaisuihin ja myös julkaisujen järjestelmän sisäiset nimet voivat joissakin tilanteissa olla käytössä myös osana niitä. Järjestelmämuuttuja {{PublicationName}} hakee tämän arvon osaksi sisältöä.
Sen sijaan nimeämistä voi käyttää sisäisen dokumentaation tukena ainakin seuraaville palasille:
- Otsikkosisältöjen kansiot,
- Otsikkopuut,
- Tagit ja niiden kategoriat,
- Muuttujat,
- Liitetiedostot ja niiden kansiot,
- Elementtiluokat,
- Tyylit ja tyylitiedostot ja
- Työnkierron tilat.
Sen lisäksi, että hyvät nimet vihjaavat oikeista käyttötavoista ja helpottavat näkymien suodattamista oikeiden osuuksien löytämiseksi, niihin liittyy myös muita huomioita.
Käytä englanninkielisiä nimiä eri palasille. Tulevat kirjoittajat eivät välttämättä osaa muita kieliä kuten suomea. Jos osa järjestelmästänne on rakennettu suomeksi, he eivät tule muistamaan oikeita käyttötapoja ilman erillistä ohjeistusta. He ovat tällöin täysin riippuvaisia ohjeistuksesta.
Muuttujia nimetessäsi aakkosjärjestys vaikuttaa niiden toimintaan. Kaikki muuttujat näytetään aakkosjärjestyksessä tekstieditorin listassa (seuraavan päivityksen jälkeen). Lisäksi julkaisumuuttujat kuitenkin näytetään aakkosjärjestyksessä myös julkaisukohtaisia arvoja muokattaessa. Jos siis tietyt julkaisumuuttujat liittyvät toisiinsa vahvasti ja on tärkeää esittää ne peräkkäin, voi niiden alkuun lisätä tunnisteita kuten ’aaa_’. Nämä alkutunnisteet helpottavat julkaisumuuttujien järjestyksen hallinnointia. Näiden tunnisteiden on syytä jättää tilaa myös lisäyksille aiempien julkaisumuuttujien väliin mahdollisten tulevien tarpeiden huomioimiseksi. Kirjaa sisäisiin oppaisiin, mistä näiden tunnisteiden käytön osalta on kyse ja millä perusteella niiden arvot määritetään.
Kuvaukset
Kuvaukset antavat lisätä yksityiskohtaisempia tietoja palasen oikeista käyttötavoista. Lisäksi niihin voi lisätä avainsanoja ja muita tunnisteita, jotka antavat löytää tietyn palasen listalta näkymän suodatuksen avulla. Tämä vaatii, että kyseisenlaisen palasen kuvaus näkyy jossakin listanäkymän sarakkeista.
DoX CMS:ssä kuvauksia voi antaa seuraaville palasille:
- Julkaisujen revisiot,
- Otsikkosisällöt,
- Tyylit,
- Käännösmuuttujien arvot,
- Käännösprojektit,
- Tyylit,
- Elementtiluokat ja
- Työnkierron siirtymät.
Näistä kuvauksista kaikki muut kuin käännösmuuttujien arvojen kuvaukset näkyvät vastaavien listanäkymien sarakkeina. Elementtiluokkien kuvaukset näkyvät myös tekstieditorin listassa elementtiluokista.
Julkaisujen revisioiden kuvaukset
Julkaisujen revisioiden kuvauksissa voit esimerkiksi kertoa, miten ne eroavat edellisistä revisioista. Lisäksi voit mainita esimerkiksi toimituskohtaiset asiakkaat tai muita ainutkertaisia tunnisteita. Jos julkaisujen revisioiden kuvauksissa on mukana avainsanoja niiden löytämiseksi näkymän suodatuksen avulla, voi avainsanat pitää kuvauksen lopussa revisiokohtaisten tietojen lisäksi.
Otsikkosisältöjen kuvaukset
Otsikkosisältöjen kuvauksissa voi kertoa niiden asianmukaisista käyttötavoista. Julkaisujen revisioiden tapaan voit lisätä tällaiset kuvaukset avainsanojen oheen tai avainsanat osana kuvauksia voi erottaa esimerkiksi tällä tavoin: ’Use this as a #template for #userManual #intro. Update the variables with new products.’ Myös tältä osin englanti toimii paremmin kuin esimerkiksi suomi kiitos sen kieliopin. Lisäsin esimerkissä avainsanojen eteen ristikkomerkin (#), jotta suodatuksen perusteena voi edelleen käyttää avainsanaa kuten ’#userManual’. Muut osuudet eivät voi vahingossa sisältää tarkalleen tätä tekstiä.
Käännösmuuttujien arvojen kuvaukset
Käännösmuuttujien arvoille voi määrittää kielikohtaiset kuvaukset. Tätä toimintoa on syytä käyttää ensisijaisesti niiden alkuperäisellä kielellä. Tämä kuvaus antaa kertoa, missä ja miten kyseistä muuttujaa on tarkoitus käyttää. Voit esimerkiksi kertoa kyseessä olevan vain kannessa tai vain osana toista muuttujaa käytetystä muuttujasta. Lisäksi voit kertoa tässä kuvauksessa, kuinka muuttujaa on tarkoitus päivittää. Esimerkiksi mallin nimen sisältävä muuttuja päivitetään normaalisti lisäämällä sen sisään uusi fraasielementti (ph), kirjoittamalla lisättävän mallin nimi tämän elementin sisään ja lisäämällä sille mallia vastaava tagi samasta tagikategoriasta kuin muille saman muuttujan osille.
Tyylien kuvaukset
Tyylien kuvauksia voi myös käyttää niiden oikeiden käyttöpaikkojen kirjaamiseen. Tämä on erityisen tärkeää tyylien tapauksessa, koska enemmistö käyttäjistä ei osaa lukea niiden käyttämiä HTML ja CSS -tiedostoja selvittääkseen oikeat käyttötavat itse. Olennaisia tietoja ovat esimerkiksi, minkä tiedostotyypin toimituksiin tyyli soveltuu ja miten se eroaa mahdollisesta oletustyylistä.
Elementtiluokkien kuvaukset
Elementtiluokkien kuvauksien tarkoitus on kertoa, mitä muutoksia niihin liittyy ja mihin elementteihin elementtiluokkia on tarkoitus käyttää. Niihin liittyvät säännöt tyylitiedostossa useimmiten olettavat kohteen olevan tietynlainen elementti kuten täyden taulukon kehys eikä itse sen taulukkoelementti. Et voi muokata vanhojen elementtiluokkien kuvauksia suoraan. Sen sijaan voit turvallisesti poistaa alkuperäisen elementtiluokan ja lisätä tilalle uuden elementtiluokan samalla nimellä sekä uudella kuvauksella.
Työnkierron siirtymien kuvaukset
Voit lisätä työnkierron tilojen muokkauksen yhteydessä kuhunkin tilaan liittyviin seuraaviin siirtymiin kuvauksen tilanteista, joissa tätä siirtymää on tarkoitus käyttää. Käytä tähän siirtymäkohtaista Toiminto-kenttää. Vaikka näitä tietoja ei näytetä muualla, ne antavat uusien käyttäjien ymmärtää, kuinka työnkiertoa on tarkoitus käyttää. Tämä on erityisen tärkeää, kun työnkiertoon liittyy poikkeavuuksia, lisätiloja tai haarautumia.
Kommentit
Kommentit ovat tarkemmin kohdistettuja kuin kuvaukset. Useimmiten niiden tarkoitus on selittää jokin tilannekohtaisesti tehty muutos tai valinta, jotta kyseisestä aiheesta löytyy edes jonkinlaista kirjanpitoa.
DoX CMS:ssä käytettävissäsi ovat nämä kommentoinnin muodot:
- Revisiokommentit,
- Editorikommentit,
- Katselmointikommentit,
- Tyylitiedoston kommentit,
- Työnkierron kommentit ja
- Käännöskommentit.
Revisiokommentit
Revisiokommentit antavat kertoa otsikkosisältöjen kuhunkin revisioon liittyvistä muutoksista. Tämä antaa jäljittää sisältöjen muutoshistoriaa ja palauttaa käyttöön malleja aiemmista revisioista, jos jokin muutos kumotaan. Jos revisiokommentit ovat vakioituja, antavat ne myös suodattaa Editori-näkymää aktiivisten revisioiden revisiokommenttien perusteella.
Editorikommentit
Voit lisätä tekstieditorissa elementtikohtaisia kommentteja, jotka näkyvät vain tekstieditorissa (tai jos tyylitiedosto pakottaa ne näkyviin esimerkiksi koejulkaisuissa). Tällaiset kommentit antavat selittää poikkeuksellisia tai tarkkarajaisia toimintatapoja. Ne voivat myös kertoa tekstieditorissa muutoin ei-ilmeisistä seikoista kuten sisältöviitteiden (conref) käytöstä.
Katselmointikommentit
Katselmoinnin yhteydessä lisätyt kommentit näkyvät tekstieditorin Kommentit-kentässä. Niitä voi lisätä myös tekstieditorin kautta ilman katselmointitoiminnon käyttämistä. Näiden kommenttien avulla välitetään muutospyynnöt katselmoinnin yhteydessä havaittuihin seikkoihin. Niitä voi kuitenkin käyttää myös revisiokohtaisten muiden huomioiden lisäämiseen, kun nämä huomiot eivät sovellu revisiokommenteiksi tai editorikommenteiksi.
Tyylitiedoston kommentit
CSS antaa lisätä tyylitiedostoihin kommenttiosuuksia tunnisteiden ’/*’ ja ’*/’ väliin. Näiden kommenttien avulla voit lisätä tyylitiedostoihin osuuksia, jotka eivät vaikuta niiden toimintaan. Kommentteja voi käyttää tyylitiedoston jäsentämiseen, valitsijoiden selventämiseen, elementtiluokkien käyttötapojen selventämiseen, yksittäisten sääntöjen selittämiseen ja niin edelleen. Niiden avulla voi myös lisätä viitteitä esimerkiksi toistuvien värien värikoodien osalta, jos kasaaja ei anna käyttää tähän CSS-muuttujia.
Työnkierron kommentit
Kun siirrät sisältöä uuteen työnkierron tilaan, voit lisätä mukaan kommentin. Tämä kommentti näkyy valitulle käyttäjälle hänen tähän liittyen saamassaan sähköpostissa. Lisäksi kaikki työnkierron kommentit näkyvät kuitenkin myös Revision Tiedot -valikossa niihin liittyvien varauksien yhteydessä. Tällä tavoin voit siis kirjata ylös revisiohistoriaa koskevia huomioita. Tällaiset huomiot voivat myöhemmin auttaa esimerkiksi paikantamaan, miksi jokin virhe on jäänyt hyväksyttyyn versioon.
Käännöskommentit
Käännöskommenteista ei jää mainintoja järjestelmään. Ne ovat ainoastaan osa sähköpostiviestiä, joka lähetetään valitulle käyttäjälle. Niin kauan kuin kyseiset sähköpostiviestit tosin arkistoidaan, myös nämä kommentit voivat auttaa jäljittämään aiempia järjestelmän käyttötapoja. Tämä on erityisen hyödyllistä, jos esimerkiksi käännöksien osalta havaitaan myöhemmin virheitä tai muuta odottamatonta käytöstä.
Sisäinen dokumentaatio liittyen DoX:iin
Yllä kuvatut DoX CMS:n sisäiset kirjaamiskeinot eivät riitä rakenteisen dokumentaation ylläpidon vaatimien toimintamallien dokumentointiin. Niiden lisäksi tarvitaan myös erillinen sisäinen tyyliopas, joka kertoo tarkemmin aiemman sisällön muotoilussa mukana olevista olettamista.
Käyn alla läpi DoX CMS:n yksityiskohtia, joihin liittyen on syytä ylläpitää sisäistä dokumentaatiota.
Kieliasu
Kieliasu kattaa yleiset sisällön muotoilun periaatteet lausetasolla. Tämä ei ole vain rakenteiseen kirjoittamiseen liittyvä seikka. Yhtenäisen tyylin saavuttaminen vaatii opastusta koskien seikkoja kuten kielioppia ja sallittua sanastoa.
Lauseiden muotoilu
Lausetasolla muotoilun on syytä huomioida sekä lauseiden pituus että niiden kielioppi. Esimerkiksi ASD-STE100:n kahdeksas laitos sallii kirjoittaa 20 sanaa pitkiä ohjaavia lauseita ja 25 sanaa pitkiä kuvaavia lauseita. Jos käytössänne on tällaisia sääntöjä, ne täytyy kirjoittaa ylös.
Huomioitavia kieliopillisia seikkoja ovat esimerkiksi seuraavanlaiset yksityiskohdat:
- Passiivin käyttö: Usein on tärkeää kertoa, missä yhteyksissä passiivin käyttö sallitaan, ellei sen käyttö ole täysin kiellettyä.
- Persoonamuodot: Passiivin voi joskus korvata puhuttelemalla lukijaa käyttäen eri persoonamuotoja. Esimerkiksi yrityksestänne voi puhua monikon toisessa persoonassa (’me’). Tätä koskevat säännöt ja rajoitukset on kuitenkin syytä kirjata ylös.
- Aikamuodot: Yleensä aikamuodot on syytä rajata vain mahdollisimman yksinkertaisiin. Kerro järjestelmänne käyttäjille, mitä aikamuotoja he saavat käyttää.
- Sidesanat: Sidesanoja kannattaa käyttää. Usein on kuitenkin syytä rajoittaa, mitkä niistä ovat sallittuja, ja määrittää, millä niistä saa aloittaa lauseita.
- Johdesanat: Usein toisista sanoista johdettujen sanojen kuten verbeistä johdettujen substantiivien käyttöä on syytä rajata. Kirjaa ylös tätä koskevat säännöt.
Sanasto
Sanasto määrittää sallitut, kielletyt ja suositellut sanat eri tilanteisiin. Kaikkien on syytä määrittää sanasto heidän tuotteeseensa liittyville avainsanoille ja lyhenteille. Lisäksi voit käyttää kattavampaa listaa sallituista sanoista kuten ASD-STE100:n sanakirjaa tai sen tarpeisiinne vastaavaa sovitusta.
Lista tuotteeseen liittyvistä avainsanoista ja lyhenteistä antaa määrittää niiden tarkat kirjoitusmuodot. Avainsanojen ei tarvitse olla ainutkertaisesti omiin tuotteisiinne liittyviä, vaikka moni niistä varmasti on tällä tavoin teille ominaisia. Kyse voi olla tiettyihin tuotteidenne osiin viittaamiseen valituista sanoista, kuten onko kyseessä ’telakka’ vai ’liitoskohta’. Erityisen tärkeää on määrittää avainasemassa olevien yhdyssanojen kirjoitusasu: milloin käytätte väliviivoja tai välilyöntejä ja milloin kirjoitatte sanat yhteen. Helpoin tapa ilmaista tämä on kirjata ylös oikeat sanamuodot ja niiden käyttötavat.
Myös muita sanoja kuten sallittuja verbejä koskeva sanasto on tärkeä osa tyyliopasta. Ihanteellisesti se sisältää myös kielletyt sanat, joiden osalta olette kirjanneet ylös samoissa tilanteissa sallitut vaihtoehtoiset sanat tai kiertoilmaisut. Kirjatkaa ylös myös merkitykset, joiden ilmaisemiseen kutakin sanaa saa käyttää ja vaihtoehtoiset sallitut sanat monimerkityksisen sanan muille merkityksille. Esimerkiksi sana ’valitse’ voi olla liian monimerkityksinen, jolloin tekstin osuuden valitsemiseen voi määrittää sallituksi sanaksi ’värjää’ sen sijaan.
Editorikäytänteet
Editorin osalta on syytä huomioida muutakin kuin kieliasu. Sisällön järjestelyyn liittyy usein sääntöjä siltä osin, mitkä elementit lisätään otsikkosisältöjen alkuun ja mitkä niiden loppuun. Myös esimerkiksi listojen ja kuvien suhde voi vaihdella. Vain osaa kuvista saattaa saada käyttää listojen sisällä. Mahdollisesti listat on määritetty jatkuviksi tavalla, joka antaa lisätä kuvia niiden väliin.
Huomioitavia seikkoja tekstieditorin käyttötapojen osalta ovat esimerkiksi seuraavat yksityiskohdat:
- Sisällön järjestely: Sisällön järjestelyn periaatteisiin vaikuttavat varsinkin tyylitiedosto ja sivuasettelun ennakointi suhteessa käyttötapoihin. Jos tyylitiedostoon on kirjattu sääntöjä kuten että listat alkavat aina samalta sivulta kuin niitä edeltävä tekstikappale, kaikkien listojen eteen täytyy lisätä tähän tarkoitettu tekstikappale. Sivuasettelu puolestaan liittyy esimerkiksi siihen, mitkä osuudet alkavat uudelta sivulta ja kuinka suuret elementit asettuvat sivujen välillä. Kirjaa kaikki tällaiset toimintamallit tyylioppaaseenne.
- Osioiden käyttö: Otsikkosisällöt voi jakaa osioelementteihin (section). Niiden käytön hyödyllisyys vaatii usein niiden laajempaa käyttämistä, jotta esimerkiksi sisältöviitteet (conref) saa asettumaan muun sisällön väliin. Jos osioita täytyy siis käyttää kaikkialla tai määrätyiltä osin, kerro siitä tyylioppaassanne.
- Metadata: Jos käytätte prologikenttää ja sen dataelementtejä, kirjatkaa ylös, millaisia arvoja kussakin otsikkosisällössä täytyy kirjata ylös tällä tavoin. Jos osa näistä elementeistä on sisäkkäisiä, kertokaa myös näistä suhteista niiden välillä.
- DITA-attribuutit: Kunkin elementin DITA-attribuutit antavat hallinnoida sille ominaisia seikkoja kuten tekstin asettumista taulukoissa. Yleensä tällaisia seikkoja on parempi hallinnoida tyylitiedoston kautta, mahdollisesti elementtiluokan avulla. Jos kuitenkin DITA-attribuutteja on käytetty osana dokumentaatiota, siitä tulee kertoa tyylioppaassanne saman käytänteen jatkamiseksi.
- Sisältöviitteet ja muuttujat: Sekä sisältöviitteet (conref) että muuttujat antavat yksilähteistää palasia otsikkosisältöjen välillä. Tällöin yksi lähdeversio hallinnoi samansisältöisiä toistuvia kohdeversioita. Käyttäjien täytyy kuitenkin tietää, milloin ja mitä yksilähteistettyjä versioita heidän tulee käyttää näiden järjestelmien hyödyntämiseksi.
- Ehdollistaminen: Tagien käyttö ei ole täysin yksiselitteistä. Myös siihen liittyen on syytä kirjoittaa ylös ohjeistusta: mitkä osuudet ehdollistetaan toisilleen rinnakkaisina vaihtoehtoina, onko käytössä sisällöltään ehdollistettuja muuttujia, ja niin edelleen. Jos ehdollistatte osan sisällöistä eri tavoin, nämä osuudet voivat näyttää erilaisilta kuin muu sisältö. Seassa voi myös olla tarpeettomasti kopioitua sisältöä, joka ei tämän seurauksena ole enää yksilähteistettyä.
- Elementtiluokkien käyttö: Elementtiluokkien nimet ja kuvaukset eivät usein voi kertoa kaikkea niiden käytöstä. Varsinkin elementtiluokkien ollessa välttämätön osa sisällön muotoilua, niiden käyttötavat on syytä käydä läpi myös tyylioppaassanne.
Tyylitiedostojen kuvaukset
Useimmat käyttäjät eivät osaa lukea tai kirjoittaa CSS:ää eikä sitä voi odottaa heiltä. Tästä syystä heidän kirjoittamisprosessinsa kannalta olennaiset tyylitiedoston seikat on syytä kirjoittaa tyylioppaaseen. Yllä on mainittu esimerkkejä kuten listoja edeltävät tekstikappaleet, jos ne on pakotettu samalle sivulle listan kanssa. Lisäksi on kuitenkin syytä kirjoittaa listat esimerkiksi seuraavia seikkoja koskevista säännöistä:
- Kannet: Kansien toteutukseen löytyy monia keinoja. Usein ne ovat kuitenkin todella riippuvaisia tyylitiedostosta eri osien asettelun ja vakioidun taustakuvan osalta. Nämä seikat on syytä selventää tyylioppaassanne, jotta muut käyttäjät voivat tarvittaessa tehdä muutoksia kansiin. Lisäksi heidän täytyy tietää joissakin toteutustavoissa, kuinka uudet kannet täytyy muotoilla.
- Sivutunnisteet: Sivujen ylä- ja alatunnisteiden tietoja tarvitsee muokata ajoittain. Käyttäjät tarvitsevat sen tekemiseen tiedon tavasta, jolla sivutunnisteet on rakennettu.
- Sivunvaihdot: Sivunvaihtojen hallinnoinnin säännöt voivat usein hämmentää käyttäjiä. Tämän helpottamiseksi pidä yllä listaa säännöistä koskien kiellettyjä ja pakotettuja sivunvaihtojen sijainteja. Pyri myös selittämään syyt näille säännöille. Tällä tavoin muut käyttäjät eivät muuta niitä tilannekohtaisten asetteluiden parantamiseksi ymmärtämättä alkuperäisiä perusteita.
- Elementtiluokat: Vaikka muualla kerrottaisiin elementtiluokkien käytöstä, on niihin liittyvät säännöt silti syytä kerrata tyylitiedoston kuvauksessa. Tämä osuus voi olla täysin kuvaava ohjeistavan sijaan.
- Otsikot: Eri tason otsikoiden toteutustavat on syytä mainita. Näiltä osin voi olla syytä mainita esimerkiksi vakioidun numerotunnisteen osuuden leveys. Muut käyttäjät pystyvät tällöin huomioimaan käytettävissä olevan tilan, kun he kasaavat sisältöpuita. Jos esitelmäkenttiä (shortdesc) käytetään osassa tai kaikissa sisällöissä, myös se on syytä mainita.
- Huomioelementit: Huomioelementit (note) vaativat usein muutoksia tyylitiedostoon käyttäjien osalta, jotta niiden otsikot saa käännettyä. Tästä syystä tiedot koskien niitä ovat erityisen tärkeitä. Kerro, mihin tyyppeihin liittyy muotoilusääntöjä ja onko niiden lisäksi tarpeen käyttää esimerkiksi elementtiluokkia käytettyjen symboleiden vaihtamiseksi vastaamaan vaaran luonnetta kuten sähkövaaraa.
- Taulukot: Taulukot ovat kaikkein monimutkaisin elementtityyppi. Jos niihin liittyviä sääntöjä tyylitiedostossa ei huomioida kirjoitusvaiheessa, voi se rikkoa niiden asettelun. Esimerkiksi sarakekohtaiset syvennykset tai vuorottelevat rivien tai sarakkeiden taustavärit eivät sovellu yhteen jaettujen ja yhdistettyjen solujen kanssa.
- Kuvat: Jos kuvien koon hallinnointi tehdään tyylitiedoston kautta, kerro käyttäjille sitä ohjaavista periaatteista ja säännöistä. Näin he voivat tarvittaessa säätää kuvien kokoa. Se myös auttaa välttämään tilanteet, joissa he määrittävät tarpeettomasti kuvakohtaisia arvoja tekstieditorin kautta. Tekstieditorissa määritettyjen kuvakohtaisten arvojen päivittäminen halki eri kielien on haaste.
- Listat: Listojen kuvauksissa on syytä lähinnä mainita, kuinka sisennetyt listat toimivat ja kuinka niitä on tarkoitus käyttää. Jos käytössä on myös erillinen numerointikeino, joka esimerkiksi aloittaa listojen numeroinnin alusta vain otsikkosisältöjen välillä, täytyy muille käyttäjille kertoa tästä tyylioppaassanne.
Työnkierto
Työnkiertoa on syytä kuvata lähinnä, kun siihen liittyy teille ominaisia poikkeamia oletustyönkierrosta. Tällaisia ovat esimerkiksi lisätilat ja poikkeavat sallitut siirtymät. Ihanteellisesti sisäisen työnkiertonne voi esittää siirtymäkaaviona. Muussa tapauksessa esimerkiksi lista työnkierron tiloista ja niihin liittyvistä siirtymistä on myös mahdollinen. Tällä tavoin käyttäjille on selvää, kuinka heidän on tarkoitus käsitellä sisältöä tekstieditorin ulkopuolella. Työnkierto liittyy muihin toimintoihin kuten sisällön katselmointiin ja käännöspyyntöihin.
Käännöskäytänteet
Myöskään käännöksien hankkiminen ei ole täysin yksiselitteistä. Niihin liittyvät sisäiset käytänteenne on syytä kirjata ylös. Tällaisia huomioita ovat esimerkiksi nämä seikat:
- Käännöspohjan valmistelu: Kirjatkaa ylös, mitä kaikkea alkuperäisellä kielellä täytyy tehdä ennen käännöspyynnön lähettämistä. Yleensä tämä vaatii sekä otsikkosisältöjen että julkaisujen revisioiden työnkierron päätöksen saattamista. Tällä tavoin käännöksiin liittyvä korjauksien tarve muutoin kuin kääntäjien erheiden osalta on mahdollisimman pieni. Myös tagit siirretään kielien välillä käännöspyyntöjen avulla. Varmistakaa, että kaikki sisältö on ehdollistettu senhetkiseen lopulliseen muotoonsa.
- Käännöspyynnön lähettäminen: Myös käännöspyyntöihin voi liittyä erilaisia käytänteitä. Esimerkiksi julkaisujen käännöksissä on tärkeää noudattaa aiempia käytänteitä, mitä tulee revisioiden lukitsemiseen kohdekielen käyttöön. Muussa tapauksessa kohdekielen julkaisun käyttöön voivat periytyä ja jäädä voimaan väärät revisiot käännöksistä.
- Vakioidut vieraskieliset ilmaisut: Jos tietynkielisissä käännöksissä täytyy käyttää vakioituja sanoja esimerkiksi omille teknisille käsitteillenne, on ne syytä kirjoittaa ylös. Tällä tavoin ne saadaan välitettyä myös kääntäjien käyttöön.
- Käännöstiedoston ulkopuoliset käännökset: Kaikki sisältö, joka voi tarvita kääntää, ei ole yhteensopivaa käännöstiedostojen kanssa. Käännöstiedostot sisältävät vain varsinaiset kirjoittamanne sisällöt ja valittujen muuttujien arvot. Jos käytätte käännöstä vaativia kuvia tai tyylitiedoston osia kuten huomioelementtien (note) otsikoita, kertokaa sisäisessä dokumentaatiossanne, kuinka niiden käännökset hankitaan ja otetaan käyttöön.
- Käännösversioiden hallinnointi: Eri kielten revisiot sisällöistä ovat itsenäisesti hallinnoitavia. Jos esimerkiksi kuvien linkit täytyy vaihtaa käännettyihin kuviin, täytyy se tehdä erikseen kullakin kielellä. Voitte ohittaa tähän liittyvät riskit ja vaivan ennakoimalla tällaiset tarpeet ennen sisältöjen lähettämistä käännettäviksi. Kuvien käännöksiä voi hallinnoida helposti liitetiedostojen valikossa, kun kuvaelementtien kohteiksi on määritetty kuvakäännökset. Lisäksi kuvien kokoa ja muita tekstieditorin kautta tehtäviä valintoja voi hallinnoida halki kaikkien kielten esimerkiksi elementtiluokkien avulla.
- Käännöksien tuonti: Myös käännökset järjestelmään tuodessanne täytyy huomioida seikkoja, kuten kuka tuo sisällöt ja kuinka poikkeamat tältä osin täytyy huomioida. Kirjatkaa kannaltanne oikeat toimintamallit ja niiden syyt ylös tuleville käyttäjille.
Yhteenveto
Ylläpitäkää DoX CMS:n käytön ohessa mahdollisimman kattavaa sisäistä dokumentaatiota oman ympäristönne oikeista käyttötavoista. Tällä tavoin oikeat tavat toimia ovat saatavilla, kun käyttäjät vaihtuvat. Käyttäjien vaihtumiseen liittyvät riskit pienenevät huomattavasti, kun uusien käyttäjien ei tarvitse päätellä tai arvata, kuinka järjestelmää on tarkoitus käyttää. Rakenteisen kirjoittamisen järjestelmät vaativat yhteneväisiä käyttötapoja dokumentaation laadun ylläpitämiseksi ja järjestelmiin liittyvien hyötyjen saamiseksi.
Järjestelmän sisällä muistiinpanojen ylläpitäminen koostuu selvistä, käyttötarkoitukseen viittaavista nimistä, tarkentavista kuvauksista ja lisätietoja antavia kommentteja. Näillä voidaan ohjata käyttäjiä ja muistuttaa heitä tilannekohtaisesti oikeista käyttötavoista. Ne eivät kuitenkaan ole riittävä sisäisen ohjeistuksen muoto. Niiden lisäksi tarvitaan myös erillinen sisäinen ohje.
Erillisen sisäisen tyylioppaan tulee huomioida sekä käytettävissä oleva kieliasu että oikeat toimintamallit eri tilanteissa. Kieliasun ohjeistus koostuu lauseiden muotoilusta kuten kieliopillisista rajoituksista sekä sanastosta. Sanaston täytyy kattaa ainakin avainsanat ja tekniset ilmaisut. Lisäksi se voi kuitenkin sisältää myös laajemman sanakirjan, joka kertoo sallitut ja kielletyt ilmaisut eri tilanteissa. Toimintamallit koskevat esimerkiksi editorikäytänteitä, tyylitiedoston käyttöä, työnkiertoa ja käännöskäytänteitä. Niiden tarkoitus on varmistaa sisältöjen ja toimintatapojen yhteneväisyys halki järjestelmän. Tällä tavoin keskenään vuorovaikuttavat järjestelmät pysyvät koordinoituina tavalla, joka ylläpitää niiden kykyä tuottaa odotetunlaisia tuloksia varsinkin julkaisujen kasaamisvaiheessa.