Tämä lyhyt artikkelisarja on tarkoitettu heille, jotka harkitsevat siirtymistä rakenteiseen dokumentointiin. Tämä ensimmäinen osa käsittelee eroja suoraan tekstinkäsittelyohjelmiston kautta muotoillun pohjamateriaalin ja rakenteiseen muotoon kirjoitetun pohjamateriaalin välillä. Jos molempien odottaa toimivan samalla tavoin, on vaikeaa saada rakenteisesta dokumentoinnista irti siihen kuuluvia hyötyjä.
Koska kyseessä on selonteko rakenteiseen dokumentointiin käytännössä perehtymättömille, selvennetään alla ensin, mitä käytänteitä rakenteinen dokumentointi kattaa sekä mitä hyötyjä se tarjoaa. Artikkelin loppuosa keskittyy erinäisiin eroihin perinteisen tekstinkäsittelyn ja rakenteisen dokumentoinnin välillä. Näihin eroihin lukeutuvat (1) siirtymä mikromanageroinnista sisällön säännöllistämiseen, (2) sisällön ehdollistaminen ja (3) viitemuotoinen sisällön hallinnointi.
Rakenteinen Dokumentointi Pähkinänkuoressa
Rakenteisen dokumentoinnin ydinajatus on sisällön jakaminen taustalla vaikuttavan kaavan mukaisiin palasiin, joita on mahdollista käyttää uudelleen eri yhteyksissä ja joihin voidaan kohdistaa erikseen määritettyjä muotoiluja.
Tältä osin isona erona esimerkiksi MS Wordiin pohjautuvaan tekstinkäsittelyyn on, kuinka kaikki sisältö on suoraan siirrettävissä samaa kaavaa käyttävien dokumenttien ja järjestelmien välillä.
Kuvittele esimerkiksi tekeväsi tarkkaan aseteltu taulukko MS Wordissa ja yrittäväsi ensin kopioida ja sitten liittää koko taulukon eri tekstinkäsittelyohjelmistoon.
Kuinka luultavana pidät aiemman kokemuksen perusteella, että taulukko saadaan siirrettyä sellaisenaan tällä tavoin?
Enemmistö myöntänee, että ainakin osa taulukosta luultavasti rikkoutuu osana prosessia.
Rakenteisen dokumentoinnin tapauksessa taulukon rakenne perustuu kaavaan, joka puolestaan perustuu laajemmassa käytössä olevaan metakieleen. Näihin metakieliin lukeutuvat esimerkiksi verkkosisältöihin käytetty HTML ja tekniseen dokumentointiin tarkoitettu DITA. Jos siis kaavan mukaisesti rakennettu elementti kopioidaan dokumentista, sen voi liittää vapaasti mihin tahansa yhteyteen, missä käytetään samaa pohjakaavaa. Yksittäisen ohjelmiston sijaan sama materiaali soveltuu useampiin asiayhteyksiin ja se voidaan tarvittaessa jopa poimia sisällöistä automatisoidusti kiitos kaavojen sisältämien tunnisteiden.
Koska rakenteinen dokumentointi siis perustuu yksittäisistä ohjelmistoista itsenäisiin kaavoihin ja koska sisällöt jaetaan itsenäisesti käsiteltäviin palasiin, voi yksittäisiä palasia ottaa käyttöön itsenäisesti eri asiayhteyksissä tarpeen mukaan. Täten sen avulla on esimerkiksi mahdollista hallinnoida uudelleenkäytettyjä sisältöjä yksittäisten lähdeversioiden avulla. Rakenteinen dokumentointi vähentää näin sekä kirjoittamisen vaatimaa työmäärää että sisällön päivittämiseen liittyviä riskejä.
Tarkempia selityksiä aiheesta löytyy muualta. Esimerkiksi tämä vanhempi artikkeli selittää tarkemmin aiheeseen liittyvää teknistä sanastoa.
Kolme Huomioitavaa Eroa Pohjamateriaaleissa
Siirtyminen rakenteiseen dokumentointiin tarkoittaa osaltaan erilaiseen toimintaympäristöön totuttelemista. Suorien tekstinkäsittelyohjelmistojen kuten MS Wordin etuihin lukeutuu, kuinka työympäristö käytännössä vastaa lopputulosta. Useimmiten sama ei pidä paikkaansa rakenteisen dokumentoinnin luontiympäristöjen tapauksessa. Tästä syystä on parasta, että nämä erot toimintaympäristöissä selvennetään uusille käyttäjille ja käyttöönottoa harkitseville.
Mikromanageroinnista Säännöllistämiseen
Suorien tekstinkäsittelyohjelmistojen pääetu on, että ne sallivat asetella sisällöt suoraan sivukohtaisesti. Täten kunkin sisällön sijainti lopullisessa julkaisussa on täysin ennakoitavissa. Täten niitä käyttäen on mahdollista määrittää itse jokainen dokumentin yksityiskohta siten kuin se halutaan lopulliseen versioon. Ajoittain tällaisella tarkalle ja kohdistetulla säätämiselle voi olla tarvetta. Joskus koettu tarve hallinnoida jokaista yksityiskohtaa tähän tapaan voi kuitenkin olla myös erheellistä ja perustua lähinnä tottumuksien synnyttämiin odotuksiin. Tältä osin rakenteinen dokumentointi osoittaa myös eri toimintamallien pätevyyden monissa asiayhteyksissä.
Jos siis suorille tekstinkäsittelyohjelmille ominainen toimintamalli kannustaa mikromanagerointiin tässä mielessä, voi rakenteiselle dokumentoinnille ominaista lähestymistä kutsua säännöllistämiseksi.
Säännöllistäminen tarkoittaa tässä yhteydessä sisällön asettelun kytkemistä joukkoon vakioituja sääntöjä.
Isoin ero, mikä tähän lähestymistapaan liittyy, on epäyhteneväisyys pohjamateriaalin ja lopullisen julkaisun välillä. Lopullisen julkaisun asettelun yksityiskohdat pohjamateriaalin osalta määrittyvät sovellettujen sääntöjen perusteella vasta julkaisuvaiheessa. Tästä syystä esimerkiksi sivuasettelu täytyy ennakoida rakentamalla sisältö tietoisena asettelun säännöistä ja niiden rajoituksista. Tällaisia yksityiskohtia ei voi hallinnoida suoraan osana kirjoitusprosessia.
Vaikka tämä piirre on monessa suhteessa rajoite, on se samalla ehto rakenteisen dokumentoinnin sallimalle korkealle uudelleenkäytettävyydelle. Esimerkiksi käännössisältöjen asettelua ei tarvitse tehdä uudelleen hallinnoimalla niitä varten tuotettuja uusia sisältöjä suoraan. Sen sijaan niiden automaattinen asettelu noudattaa samoja sääntöjä kuin myös alkuperäinen versio. Jos siis sisältöjen asettelu on riittävän ennakoivaa ja sitä hallinnoivat säännöt on kirjoitettu asianmukaisesti, ei käännöksien asettelu vaadi lainkaan lisätyötä.
Siirryttäessä rakenteiseen dokumentointiin tulee siis olla valmis luopumaan suoran hallinnoinnin sallimasta mahdollisuudesta mikromanageroida sisällön asettelua. Itse sisällön tuottamisen prosessi on erotettu sen asettelemisesta, mikä on omasta kokemuksestani lähinnä vapauttavaa. Samalla tulee kuitenkin huomioida, että asettelun säännöillä on rajansa ja että esimerkiksi sisällön järjestys voi vaikuttaa tapaan, jolla se asettuu. Tällaisten yksityiskohtien ennakointi on edelleen tärkeää. Esimerkiksi suuret kuvat kannattaa järjestää osioiden loppuihin, jotta niiden mahdollisesti vaatimat sivunvaihdot eivät katko muuta sisältöä keskellä osioita. Jos kyseiset osiot on puolestaan asetettu aina alkamaan uudelta sivulta, voi kuvat olla parasta asettaa niiden alkuihin.
Ehdollistettu Sisältö
Toinen merkittävä ero on, kuinka rakenteiseen dokumentointiin kuuluu useisiin eri julkaisuihin tulevien sisältöjen näyttäminen osana jaettua pohjamateriaalia. Täten samassa pohjamateriaalissa on usein mukana eri käyttöyhteyksiin tulevia sisältöjä, jolloin se ei edes sisällöltään vastaa täysin mitään yksittäistä julkaisua.
Syynä tälle on, kuinka näin mahdollistetaan jaettujen osuuksien käyttäminen useassa julkaisussa ilman tarvetta kopioida niitä tai käyttää niihin viitteitä. Ehdollistetut osuudet puolestaan sallivat erottaa esimerkiksi mallikohtaiset sisällöt lisättäväksi vain niitä koskeviin julkaisuihin. Kirjoittajien tulee siis hahmottaa mielessään, kuinka eri sisällöt asettuvat osina eri julkaisuja, kun he muokkaavat pohjamateriaalia.
Joissakin tapauksissa jopa sama sisältö voi tulla toisinnetuksi osana samaa pohjamateriaalia. Mieluiten alkuperäinen versio toimisi tällöin lähteenä, johon muut viittaavat (katso alla). Aina se ei kuitenkaan ole mahdollista. Yleisin syy tällaiselle ratkaisulle on, että johonkin muutoin jaettuun elementtiin on pakko kohdistaa julkaisukohtaisia asettelusääntöjä. Esimerkiksi toimiva sivuasettelu saattaa joissakin tapauksissa vaatia pakotettua sivunvaihtoa tietyn elementin jälkeen. Jos pakotettu sivunvaihto ei ole saatavilla omana elementtinään, voi sellaisen lisätä osana erikseen merkityn elementin asettelun sääntöjä. Kun näin merkitty versio kyseisestä elementistä ehdollistetaan käytettäväksi vain kyseisessä julkaisussa, täytyy sen vakioversio ehdollistaa tulemaan kaikkiin muihin julkaisuihin.
Rakenteinen dokumentointi kattaa useamman julkaisun sisällöt osana samaa pohjamateriaalia. Lopullisten julkaisujen sisällöt valikoituvat tästä joukosta sen mukaisesti, kuinka ne on ehdollistettu. Kyseisen pohjamateriaalin kanssa työskennellessä on siis tarpeen hahmottaa erot julkaisukohtaisten sisältöjen välillä.
Viitesisällöt
Kolmas pääero on, kuinka osana rakenteista dokumentointia kaikki julkaisuun tulevat sisällöt eivät näy osana kyseisen osion pohjamateriaalia. Näin käy, kun kyseinen sisältö perustuu muuta sisältöä lähteenään käyttäviin viitteisiin. Tällöin pohjamateriaalissa näkyy useimmiten vain tyhjä kyseisentyyppinen elementti, joka on merkitty muualta sisältönsä hakevaksi viitteeksi.
DoX CMS:n tapauksessa tämä ilmenee muutaman eri järjestelmän muodossa. Tärkeimmät niistä ovat sisältöviitteet (conref), muuttujat ja liitetiedostot.
Sisältöviitteet koostuvat lähde-elementeistä, joiden kautta viitattua sisältöä hallinnoidaan, ja viite-elementeistä, joiden sisältö vastaa lähde-elementtiä. Lähde-elementti on normaali sisältöelementti, jolle on annettu tunnistearvo. Viite-elementti on saman tyypin elementti, jonka sisällöt korvautuvat lähde-elementin sisällöillä, koska se viittaa kyseisen elementin tunnistearvoon.
Täten vain lähde-elementti näyttää sisältönsä muodossa, jossa ne tulevat mukaan julkaisuun. Osana pohjamateriaalia viite-elementit jätetään usein tyhjiksi tai niiden sisältö koostuu lyhyestä muistutuksesta koskien lähde-elementin sisältöä.
Muuttujat ovat puolestaan DoX CMS:lle ominaisia pienempiä fraasi-elementtejä, joiden sisältöä hallinnoidaan niiden ulkopuolelta. Yleensä ne sisältävät vain tekstin pätkiä, mutta niihin voi sisällyttää myös esimerkiksi kuvia. Julkaisumuuttujien tapauksessa niiden sisältö kuten senkertaisen asiakkaan nimi määritetään osana julkaisuprosessia. Pohjamateriaalissa muuttujat näkyvät vain kahteen pariin aaltosulkeita kirjoitettuina tunnisteina kuten ’{{ProductID}}’.
Liitetiedostojen kuten kuvien tapauksessa ne useimmiten näytetään osana esikatselua. Periaatteessa niiden sisältö kuitenkin haetaan käytetyn viitteen perusteella niiden suoraan pohjamateriaaliin liittämisen sijaan. Esikatselu ei välttämättä näytä näitä tiedostoja niiden lopullisessa koossa, johon vaikuttavat myös asettelun säännöt. Niitä ei myöskään saa sijoiteltua vapaasti suhteessa muihin elementteihin osana kirjoitusprosessia. Sen sijaan kaikki asettelu täytyy tehdä sääntöpohjaisesti julkaisuvaiheessa.
Koska rakenteinen dokumentointi hyödyntää viitesisältöjä, jotka eivät ole välitön osa käsiteltävää pohjamateriaalia, tulee niiden käsittely hoitaa huolella. Yleensä lähdesisällöt on hyvä säilyttää omassa, julkaisuista erillisessä sijainnissaan, josta käsin niitä voidaan hallinnoida. On myös hyvä totutella siihen, että kuvia ei voi asetella aivan yhtä vapaasti muutoin kuin tyylitiedostojen avulla.
Erojen Hyödyt
Jos käyttäjän odotukset perustuvat suorien tekstinkäsittelyohjelmien vahvuuksiin kuten vapaaseen sivuasettelun hallinnointiin, voivat yllä kuvatut rakenteisen dokumentoinnin piireet kuulostaa pelkiltä rajoituksilta. Näin ei kuitenkaan ole. Tästä syystä korostan vielä lopuksi, mitä lisäarvoa nämä erot sallivat tai mitä niiden avulla saavutetaan.
Kaikkein olennaisin saavutettu hyöty on, kuinka kaikkea julkaistavaa sisältöä ei tarvitse säätää suoraan. Tämä on erityisen hyödyllistä käännössisältöjen tapauksessa. Jos pohjamateriaali on järjestetty tavalla, joka huomioi käytetyt asettelusäännöt ja jättää liikkumatilaa kielikohtaisille eroille, jokainen kieliversio on koostettavissa automaattisesti samojen sääntöjen perusteella.
Vastaavasti myös jaettuja sisältöjä useamman julkaisun välillä saa hallinnoitua samanaikaisesti muokkaamalla yksittäisiä sisältöjä. Jos mitään tarvitsee muuttaa tai päivittää, tapahtuu päivitys samanaikaisesti jokaisessa sijainnissa, jossa sisältö on käytössä. Tämä poistaa versiointiin liittyvän riskin, että osa jaetuista sisällöistä julkaisujen välillä unohtuu aiempaan muotoon.
Esimerkiksi muuttujien avulla on mahdollista hallinnoida yhteystietojen kaltaisia yksityiskohtia jokaisessa sijainnissa samanaikaisesti. Tällöin ei ole tarpeen muistaa, missä kaikkialla niitä on käytetty, tai hakea niitä eri pohjamateriaaleista.
Kuten myöhemmissä tämän sarjan osissa tullaan näkemään, siirtymä rakenteiseen dokumentointiin vaatii jonkin verran valmistelutyötä. Esimerkiksi asettelun säännöt tulee kirjoittaa erikseen ja tämä vaatii siihen liittyvää erikoisosaamista. (DoX Systems tarjoaa tarvittaessa asiakaskohtaiset alustavat asettelusäännöt osana järjestelmän käyttöönottoa.) Tämän valmistelutyön vastineeksi tosin itse kirjoittamisprosessi voi keskittyä puhtaasti sisällön tuottamiseen. Toisin sanoen valmistelu vaatii pitkälti kertaluontoisen lisäpanostuksen, mutta näin poistetaan tarve jatkuvalle lisätyölle sisällön tuottamisen ohessa.