Rakenteinen dokumentointi

Rakenteinen dokumentointi on informaation jäsentelyä metakielen avulla. Digitaalisen informaation jäsentelyyn sopivia metakieliä ovat varsinkin SGML-standardiin pohjautuvat merkintäkielet.

Rakenteisen dokumentoinnin tarkoituksena on helpottaa dokumenttien julkaisua ja lisätä mahdollisuuksia käyttää jo kirjoitettua aineistoa uudestaan uusissa konteksteissa. Rakenteinen dokumentointi helpottaa varsinkin suurien tekstimäärien käsittelyä ja muotoilua. Yleisesti käytetyt SGML-standardiin perustuvat merkintäkielet helpottavat myös informaation siirtämistä tietojärjestelmästä toiseen.

Rakenteinen dokumentointi on usein myös modulaarista, mikä tarkoittaa asiakokonaisuuksien jakamista useammaksi pienemmäksi kokonaisuudeksi. Näitä sisältökokonaisuuksia kutsutaan moduuleiksi.

Rakenteisen dokumentoinnin juuret ovat kirjapainoalalla, jossa ennen tekstinkäsittelyohjelmien kehittymistä kirjoitettiin tekstin muotoilu käsin sivun yhteyteen. Näin määriteltiin muun muassa tekstin fontti, fontin koko, tekstin korostaminen (kursivointi, lihavointi tai alleviivaus) sekä sivulle tulevat sisennykset. Rakenteisen dokumentoinnin perusidea on sama. Tekstin yhteyteen merkitään sen rakenne, jota sitten eri julkaisualustat tulkitsevat tyyliasetustensa mukaisesti.

Rakenteista dokumentointia ei tule kuitenkaan sekoittaa esitykselliseen dokumentointiin. Rakenteisella dokumentoinnilla määritellään ainoastaan tekstin rakenne, kuten otsikot, kappalejaot ja esimerkiksi listat. Tekstin muotoilut, kuten otsikon koko, leipätekstin väri ja listan ulkoasu määritellään puolestaan esityksellisellä dokumentoinnilla.

Rakenteisen dokumentoinnin käytännöt

Rakenteisessa dokumentoinnissa tekstin osat jaetaan pieniin loogisiin kokonaisuuksiin, joita kutsutaan elementeiksi. Teksti voidaan esimerkiksi jakaa elementeillä pääotsikoksi, väliotsikoiksi ja kappaleiksi. Tekstin lopullinen ulkoasu määräytyy puolestaan sen julkaisuympäristön mukaan. Esimerkiksi eritasoisille otsikkoelementeille voidaan määritellä erilaisia tyylejä, jolloin sama sisältö näyttää erilaiselta eri julkaisualustoilla. Tästä on hyötyä varsinkin, kun sama aineisto halutaan julkaista usealla eri laitteella. Hyvä esimerkki tästä ovat verkkosivut, jotka ovat saatavilla myös mobiiliversioina.

Rakenteisessa dokumentoinnissa käytettävissä olevat elementit riippuvat siitä, millä merkintäkielellä dokumentin muotoilu tehdään. Yleisimmin käytössä ovat SGML-pohjaiset merkintäkielet, kuten HTML, XML, XHTML ja DITA.

Rakenteisille dokumenteille määritellään aina niiden dokumenttityyppi eli document type definition (DTD).

SGML-pohjaiset merkintäkielet

Pääartikkeli: SGML

Digitaalisessa julkaisemisessa yleisesti käytetyt merkintäkielet pohjautuvat SGML-standardiin. SGML on metakieli, jolla voi generoida uusia merkintäkieliä. SGML on siis eräänlainen merkintäkielten peruskielioppi, jonka pohjalta on mahdollista luoda käyttötilanteeseen sopivia "lauseita" eli elementtejä.

HTML

Pääartikkeli: HTML

HTML on verkkojulkaisuissa yleisemmin käytetty merkintäkieli. HTML-merkintäkieli ei ota kantaa tekstin sisältöön, vaan keskittyy sen rakenteeseen, mikä tekee siitä joustavan ja sopivan useaan eri käyttötarkoitukseen.

XML

Pääartikkeli: XML

XML on sekä itsenäinen merkintäkieli että standardi, jonka pohjalta voi kehittää uusia merkintäkieliä. XML on HTML-kielen tapaan yksinkertaistettu versio SGML-standardista mutta mahdollistaa HTML-kieltä monimutkaisempia rakenteita ja julkaisumuotoja.

XHTML

Pääartikkeli: XHTML

XHTML on XML-versio HTML-kielestä. Tämä tarkoittaa, että XHTML on uudelleen määritelty versio HTML-kielestä, johon on sovellettu XML-kielen standardeja.

DITA

Pääartikkeli: DITA

Varsinkin teknisessä viestinnässä suosittu DITA on XML-pohjainen merkintäkieli. DITA on suunniteltu käyttöohjeiden ja muiden vastaavien ohjaavien tekstien rakenteiseen dokumentointiin.

Esimerkki rakenteisesta dokumentoinnista

Alla on esimerkkinä Kalevalan ensimmäisen runon kaksi ensimmäistä säkeistöä rakenteisen dokumentoinnin periaatteella esitettynä. (Käytetyt elementit eivät ole käytössä edellä mainituissa merkintäkielissä, vaan ne on luotu esimerkkiä varten.)

<span><runo></span>
<br/>
<br/>
<span><otsikko>Ensimmäinen runo</otsikko></span>
<br/>
<br/>
<säkeistö>
<br/>
<säe>Mieleni minun tekevi, aivoni ajattelevi</säe>
<br/>
<säe>lähteäni laulamahan, saa'ani sanelemahan,</säe>
<br/>
<säe>sukuvirttä suoltamahan, lajivirttä laulamahan.</säe>
<br/>
<säe>Sanat suussani sulavat, puhe'et putoelevat,</säe>
<br/>
<säe>kielelleni kerkiävät, hampahilleni hajoovat.</säe>
<br/>  
</säkeistö>
<br/>
<säkeistö>
<br/>
<säe>Veli kulta, veikkoseni, kaunis kasvinkumppalini!</säe>
<br/>
<säe>Lähe nyt kanssa laulamahan, saa kera sanelemahan</säe>
<br/>
<säe>yhtehen yhyttyämme, kahta'alta käytyämme!</säe>
<br/>
<säe>Harvoin yhtehen yhymme, saamme toinen toisihimme</säe>
 <br/>
<säe>näillä raukoilla rajoilla, poloisilla Pohjan mailla.</säe>
<br/>
</säkeistö>
<br/>
</runo>

Rakenteisen dokumentoinnin edut ja haitat

Rakenteisen dokumentoinnin etuja ovat sen uudelleenkäytettävyys ja erilaiset julkaisumahdollisuudet. Joustavuutensa ja muokattavuutensa ansiosta myös rakenteisten dokumenttien päivittäminen on helppoa. Lisäksi se voi vähentää käännöskustannuksia, sillä käännettäväksi voidaan lähettää kokonaisen tekstin sijaan yksittäisiä moduuleja, jossain tapauksissa jopa yksittäisiä elementtejä. Rakenteinen dokumentointi helpottaa myös tiedonsiirtoa eri tietojärjestelmien välillä, sillä SGML- ja XML-kieliin pohjautuvat merkintäkielet eivät ole ohjelmisto- tai järjestelmäsidonnaisia.

Toisaalta rakenteisen dokumentoinnin käyttöönotto on työläs prosessi, sillä jo olemassa olevan materiaalin muuttaminen rakenteisiksi dokumenteiksi vaati paljon manuaalista työtä. Lisäksi se saattaa joissakin tapauksissa aiheuttaa koulutus- ja/tai ylläpitokustannuksia.

Rakenteinen dokumentointi Suomessa

Rakenteinen dokumentointi on yleinen käytäntö myös Suomessa, ja esimerkiksi teknisen viestinnän alalla SGML- ja XML-kielien käyttö on niin tavallista, että näiden osaamista voidaan jo pitää osana teknisen viestijän perustaitoja. Ensimmäistä kertaa rakenteinen dokumentointi sai Suomessa laajempaa huomiota Eduskunnan kirjaston järjestämässä SGML-seminaarissa joulukuussa 1994.

Rakenteista dokumentointia Suomessa on edistänyt myös Opetusministeriön rahoittama RAJU -projekti ("Rakenteinen Julkaiseminen yliopistoissa"). Projekti toteutettiin Vaasan yliopiston, Jyväskylän yliopiston ja Teknillisen korkeakoulun yhteistyönä. Jyväskylän yliopistossa projekti oli osa yliopiston laajempaa DigiPub-tutkimusprojektia.