Rakenteinen dokumentaatio ja DITA

Mika Laihanen mika.laihanen@gmail.com @mika_himself http://mikahimself.com/TECHS6 Käännöstiede (Englanti) 1999- Teknisen viestinnän ohjelma 2003-2004 Technical Writer Documentation Technology Designer Systems Support Engineer Lead Documentation & Localization Specialist Citec Information 2004 - 2011 Basware 2011-

Rakenteinen ja modulaarinen dokumentaatio Teoriaosuus: Materiaali jaetaan sähköpostitse ennen luentoja Harjoituksia ryhmissä Keskustelua ja kysymyksiä Satunnaisesti kotitehtäviä Harjoitukset: Materiaali jaetaan sähköpostitse ennen luentoja Tunneilla harjoitustehtäviä Oxygen XML Editorilla Rakenteinen teksti DITA

Kurssin tavoitteet Tutustuttaa rakenteisuuden ja modulaarisuuden periaatteisiin, taustalla olevaan teknologiaan ja työkäytäntöhin kirjoittajan näkökulmasta Antaa valmiudet toimia teknisenä kirjoittajana yrityksissä, joissa käytetään rakenteista ja/tai modulaarista dokumentointimallia

Rakenteisuuden tasot

Muotoilematon teksti Plain text –dokumentit Sisältävät vain tekstisisällön ja tarpeeksi metatietoa että teksti pystytään esittämään tekstieditorilla Ainoita muotoiluelementtejä ovat sarkaimet, välilyönnit ja rivinvaihdot Käyttökohteina ohjelmistojen lähdekoodi, sähköposti, merkintäkielet (XML, XHTML, SGML)

Muotoiltu teksti Asiakirjat, jotka sisältävät tekstisisällön ja välttämättömien metatietojen lisäksi muotoilutietoja: Fontit, fonttikoot Rivivälit Sisennykset Upotettu kuvitus

Muotoiltu teksti Useimmilla tekstinkäsittelyohjelmilla oma tiedostomuotonsa Tiedostomuodot ovat harvoin täysin yhteensopivia muiden ohjelmistojen tai aiempien ohjelmaversioiden kanssa OpenOfficen/LibreOfficen suosion myötä avoimet standardit saaneet tukea mm. MS Wordissa

<slide> <heading> <title>Rakenteinen teksti</title> </heading> <content> <bullet-list type="squares"> <bullet>Rakenteinen teksti perustuu merkintäkielten käyttöön </bullet> <bullet>Varsinaisen tekstisisällön lisäksi tiedosto sisältää tageilla merkittyjä <emph>elementtejä</emph>. Elementit määrittävät dokumentin rakenteen ja niillä merkitään erilaisia sisältöyksikköjä. <bullet>Elementit voivat sisältää tekstiä tai toisia elementtejä, ja elementtien käsittelyä voidaan tarkentaa lisäämällä elementtiin <emph type="italic">attribuutteja</emph> </bullet-list> </content> </slide>

Rakenteinen teksti Rakenteisessa tekstissä tekstin muotoilu on erotettu kokonaan sisällöstä Jokaiselle elementille voidaan rakenteista tekstiä julkaistessa määrittää sopiva muoto

Rakenteinen teksti Rakenteista tekstiä on helppo lukea koneellisesti ja siksi se soveltuu monenlaisiin käyttökohteisiin: Nettisivut, RSS-syötteet, ohjetekstit, ohjelmistojen käyttöliittymät, verkkolaskut Jotta ihmisten olisi helppo lukea rakenteista tekstiä, teksti tulkitaan ja muunnetaan useimmiten koneellisesti johonkin muuhun muotoon, esim. PDF:ksi.

Muotoiltu teksti

Ohjetekstit ja muotoiltu teksti Ohjetekstit tuotetaan tavallisilla tekstinkäsittelyohjelmilla Käyttöönotto helppoa ja edullista; toimisto-ohjelmistot asennettuna useimmissa yritystietokoneissa Ohjelmistot ennalta tuttuja eikä peruskäyttö vaadi paljon koulutusta

Työtapoja Perusmalli: Edistynyt malli: Rajallinen määrä ohjetekstejä Tekninen kirjoittaja vastuussa dokumenttien ulkoasusta Dokumentit tallennetaan kirjoittajan kiintolevylle tai verkkolevylle Edistynyt malli: Ulkoasu määräytyy varten varta vasten kehitettyjen mallipohjien mukaan Eri mallipohjat eri tyyppisiä ohjetekstejä varten Tyyliopas, joka määrittelee dokumenttien ulkoasuun liittyvät seikat Dokumentit tallennetaan dokumenttienhallintajärjestelmään (Sharepoint, Documentum)

Toimintatapojen ongelmakohtia Perusmalli: Kirjoittajat voivat muuttaa ulkoasua oman mielensä mukaan -> kirjava ulkoasuvalikoima Dokumenttiversioiden arkistointi monesti puutteellista Dokumenttiversioiden vertailu voi olla hankalaa Edistynyt malli: Dokumenttien päivittäminen voi olla hankalaa, jos työtavat eivät ole yhtenäiset Dokumenttiversioiden vertailu voi olla hankalaa, jos työkaluissa/työtavoissa ei ole otettu versiointia huomioon

Muotoillun tekstin erityispiirteitä Ohjeteksti on aina yksi, tiettyjä ohjelmistoja tukeva tiedosto Ohjetekstiä täytyy käsitellä samalla, tai yhteensopivalla, ohjelmistolla kirjoitusvaiheesta julkaisuvaiheeseen Ulkoasumuutokset täytyy tehdä yksitellen jokaiseen tiedostoon/ohjetekstiin Fonttimuutokset Taulukoiden ulkoasumuutokset Otsikkotasojen muutokset Kuvituksen päivittäminen (jos kuvat upotettu dokumentteihin)

Muotoillun tekstin erityispiirteitä Dokumenttien yhteiseen sisältöön tulevat muutokset täytyy useimmiten tehdä tiedosto kerrallaan Dokumenttien julkaisu muussa kuin alkuperäisessä muodossa vaatii monesti sisällön käsittelemistä julkaisuohjelmilla Word -> XHTML, Word -> PDF Julkaistavan sisällön rajaaminen ja julkaiseminen vain tietyille asiakasryhmille hankalaa 1. Tekijänoikeudelliset tekstit, vastuuvapaus-tekstit, varoitustekstit

Muotoiltu teksti kirjoittajan kannalta Yksi ohjeteksti - yksi kirjoittaja Kirjoittaja “omistaa” ohjetekstin Ohjetekstit käyttöopas-mallisia - sisältävät paljon erilaista tietoa (taustatietoa, ohjeita, vianetsintäohjeita jne.) Ohjetekstit julkaistaan useimmin vain paperimuodossa, joten kirjoittajalla ei ole mahdollisuutta tehdä suoria linkkejä toisiin ohjeteksteihin. Tekstuaaliset viittaukset mahdollisia. 2. Kirjoittaja omistaa ohjetekstin: Rakenne ja kaikki sisältöyksiköt tuttuja Tietää missä muodossa ja kontekstissa ohjeteksti tullaan julkaisemaan Osaa nopeasti päätellä mihin ohjetekstin osiin tuotteeseen tulevat muutokset tulevat vaikuttamaan

Harjoitus: Muotoiltu teksti Ryhmäkeskustelu: Miten tekninen kirjoittaja voi hyötyä muotoiltua tekstiä käyttävästä dokumentointimallista? Miten muotoiltua tekstiä käyttävä dokumentointimalli voi vaikeuttaa kirjoittajan elämää?

Rakenteinen teksti

Rakenteinen teksti Rakenteinen teksti on kuvailevaa. Se kertoo millainen dokumentin rakenne ja sisältö on Rakenteinen teksti ei ota kantaa dokumentin muotoiluun tai käsittelyyn Rakenteinen teksti noudattaa tiukasti tekstityypille määritettyjä rakennesääntöjä.

Rakennuspalaset: Tagit Tagit ovat merkkejä, joiden avulla elementtejä merkitään rakenteisessa tekstissä XML:ssä käytetään kolmea tag-tyypiä: Alkutagi <paragraph> Lopputagi </paragraph> Singleton-tagi <line-break />

Rakennuspalaset: Tagit Tagien nimissä saa käyttää useimpia unicode-merkkejä Nimien tulee alkaa kirjaimella, alaviivalla, tai : -merkillä Nimi ei saa alkaa XML-merkkijonolla, eikä sisältää välilyöntejä Isot kirjaimet ovat merkityksellisiä <dotNet> <this_year>2014</this_year> <sevenUps>4 btls</sevenUps> <ääkköset>åäö</ääkköset> <Auto>Lada</Auto> <.net> <this year>2014</this year> <7-ups>4 btls</7-ups> <-kulut>12€</-kulut> <Auto>Volga</auto>

Rakennuspalaset: Elementit Elementti muodostuu alkutagista, lopputagista ja niiden välissä olevasta sisällöstä Elementti voi sisältää tekstiä, muita elementtejä tai molempia Elementti voi myös sisältää attribuutteja, jotka antavat lisätietoa elementistä ja sen sisällöstä <esimerkki> <otsikko>Esimerkkiteksti</otsikko> <kappale>Tämä on lyhyt teksti, joka sisältää <korostus tyyppi="bold"> elementtejä</korostus> ja <korostus tyyppi="kursiivi"> attribuutteja</korostus> </kappale> <kappale>Tekstin joukossa voi myös olla kuvia: <kuva tiedosto="malli.jpg"/> </esimerkki>

Rakennuspalaset: Elementit Elementin sisälle voi lisätä toisia elementtejä, mutta tagit, ja siten elementit, täytyy sulkea samassa järjestyksessä kuin ne on avattu. Ulompi elementti ei siis voi päättyä ennen sisempää. <date> <year>2013</year> <month>04</month> <day>12</day> </date> <date> <year>2013</year> <month>4<day>12</month> </day> </date>

Rakennuspalaset: Attribuutit Attribuutit antavat lisätietoa elementistä tai sen sisällöstä Attribuuteilla on mahdollista vaikuttaa julkaistavan materiaalin ulkoasuun Yhdellä elementillä voi olla useita attribuutteja. Yhdellä attribuutilla voi olla useita arvoja. <puhelin merkki="Nokia"> <malli>Lumia</malli> <versio>930</versio> </puhelin> <puhelin> <merkki>Nokia</merkki> <malli versio="930">Lumia</malli> <lista tyyppi="numeroitu kursivoitu"> <kohta>Kohta 1</kohta> <kohta>Kohta 2</kohta> </lista>

Teknologinen tausta: SGML Monet nykyisin käytettävät merkintäkielet perustuvat SGML:ään SGML on metakieli – sen avulla määritetään merkintäkieliä Pääajatukset: Kuvaileva merkintäkieli Tiukat rakennesäännöt IBM:n kehittämä; SGML perustuu IBM:n 1960-luvun loppupuolella kehittämään GML-merkintäkieleen Suunniteltu suurten, pitkäikäisten tietomassojen koneelliseen käsittelyyn (hallinto, teollisuus, lakitekstit) ISO-standardi vuonna 1986 SGML ei sisällä valmiita elementtejä tai rakenteita. Kuvaileva: kertoo dokumentin rakenteesta ja ominaisuuksista, ei ota kantaa prosessointiin -> ei tule ongelmia tulevaisuudessa mahd. kehitettäviin prosessointimenetelmiin Tiukka: ankarat säännöt, jotta materiaalia voidaan käsitellä helposti softalla

Teknologinen tausta: SGML SGML antaa käyttäjälle vapauden kehittää erilaisia merkintäkieliä. Mm. XML (eXtensible Markup Language) ja HTML (Hypertext Markup Language) perustuvat SGML:ään Käyttäjä itse ratkaisee miten haluaa luokitella ja jaotella informaationsa Käyttäjä itse päättää miten elementit on fiksuinta nimetä, ja mitä lisäinfoa – attribuutteja – elementtien tulee sisältää

SGML: Esimerkkirakenteita <!DOCTYPE maatila PUBLIC "-//MIKA//Maatila DTD 1.0//FI"> <maatila> <navetta> <elain> <suku>Kana</suku> <lukumaara>8</lukumaara> <rotu>Leghorn</rotu> </elain> </navetta> <kasvimaa> <kasvi> <suku>peruna</suku> <lukumaara>200</lukumaara> <lajike>Lemin punainen</lajike> </kasvi> </kasvimaa> </maatila> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> <title>Otsikko</title> </head> <body> <p>Ensimmäinen tekstikappale.</p> <p>Toinen tekstikappale.</p> <ol type="a"> <li>Kohta a</li> <li>Kohta b</li> <li>Kohta c</li> </ol> </body> </html>

Teknologinen tausta: XML World Wide Web Consortiumin (W3C) kehittämä merkintäkieli Kehitetty tiedon rakenteen määrittämiseen sekä tiedon varastoimiseen ja välittämiseen sähköisesti SGML:n tavoin metakieli - myös XML:n avulla voidaan määrittää uusia merkintäkieliä XML ei sisällä valmiita elementtejä eikä rakenteita (XML 1.0 julkaistu 1998) Avoin standardi Johdettu SGML:sta XML on käytännössä kevyempi versio SGML:stä Validi XML-dokumentti on myös validi SGML-dokumentti

Teknologinen tausta: XML Yleinen tapa siirtää tietoa ohjelmistojen ja tietojärjestelmien välillä Voidaan käyttää käyttöliittymien määrittelyssä XML:stä on johdettu lukuisia merkintäkieliä XML:stä on johdettu myös dokumentointikäyttöön useita merkintäkieliä: DITA (Darwin Information Typing Architecture) DocBook - RSS, Atom, XHTML, SVG, WML - Lukuisilla yrityksillä käytössä yritysten itsensä määrittelemiä, XML-pohjaisia merkintäkieliä

Teknologinen tausta: HTML Hypertext Markup Language SGML:n avulla määritelty merkintäkieli, eli SGML-sovellus HTML:n avulla ei voida määrittää uusia merkintäkieliä Kehitetty webbisivujen rakentamiseen ja kuvaamiseen – Osa elementeistä sisältää muotoiluohjeita Yksi tunnetuimmista merkintäkielistä http://www.w3schools.com/html/default.asp

Harjoitus: Rakenteinen teksti Pohdi mitä elementtejä viereinen teksti sisältää? Voisivatko jotkin elementit sisältää myös attribuutteja? From: John Acronym <john.acronym@company.com> To: Arthur Pewtey <arthur@wedesign.net> Date: 16.09 2014 Subject: Re: Proposal ----- Dear Arthur, I found your latest proposal for our website refresh rather disappointing. Just a few examples: - You used none of the clipart illustrations we provided - You had changed the font from “Comic Sans” to “Helvetica” - You had removed the scrolling, flashing banner text For the next draft, we expect the following changes to be made: 1) Use the illustrations we sent. They are dead funny. 2) Change the font back to “Comic Sans”. 3) No more of this I am a designer, I know best nonsense. We want the scrolling texts back! They catch people’s attention! Best Regards, John Acronym, Senior Marketing Manager

Rakenteisen tekstin käyttöönotto

Millaiseen käyttöön rakenteinen teksti soveltuu? Yrityksille ja organisaatioille, jotka käsittelevät suuria dokumenttimääriä Yrityksille, jotka julkaisevat materiaalia monissa eri muodoissa (web, painetut ohjeet, PDF) Yrityksille, joiden ohjeista täytyy voida hakea tietoa mahdollisimman tehokkaasti Yrityksille, joilla on useita samankaltaisia tuotteita

Tarveanalyysi Rakenteiseen tekstiin siirtyminen on työlästä ja kallista Olemassa olevien tekstien muuntaminen rakenteisiksi Kirjoittajien kouluttaminen Työkalujen valinta, hankinta, ja ylläpito Rinnakkaisten järjestelmien käyttö siirtymäaikana

Tarveanalyysi Saavutetaanko rakenteisen tekstin avulla kustannussäästöjä? Nopeutuuko tai helpottuuko kirjoittajien työ? Nopeutuuko dokumenttien julkaisu ja levittäminen?

Dokumenttianalyysi Prosessi, jossa pyritään tunnistamaan millaisista rakenteista organisaation ohjetekstit koostuvat ja millaisia rakenteita organisaatio tarvitsee pystyäkseen viestimään tehokkaasti ja onnistuneesti Tehdään useimmiten työryhmissä ja useassa vaiheessa Ostettavissa myös palveluna Prosessin päämääränä on toimivan DTD:n laatiminen Toimivan DTD:n avulla voidaan tuottaa organisaation tarvitsemaa dokumentaatiota niin, että tuotetut tekstit ovat yhteneväisiä ulkoasultaan ja rakenteiltaan

DTD Document Type Definition DTD on uuden merkintäkielen perusta DTD:n avulla määritetään mm.: Mitä elementtejä dokumentissa täytyy käyttää Mitä elementtejä dokumentissa voidaan käyttää Mitä elementtejä elementit voivat sisältää Missä kohtaa dokumentin rakennetta elementtejä voidaan käyttää Mitä attribuutteja elementit voivat sisältää Ollakseen käytettävä DTD:n ei tulisi sisältää liikaa elementtejä Elementtien määrää voi rajata esim. attribuuttien avulla

DTD Elementti Sallittu sisältö Document Title, Paragraph, List Title Teksti Paragraph Bold, Italic, Undelined, teksti List ListItem List, Paragraph, teksti Bold Italic Underlined

Harjoitus: DTD Suunnittele yksinkertainen DTD, joka kuvaa edellisessä tehtävässä olleen sähköpostiviestin rakennetta. Mitkä elementeistä ovat pakollisia, mitkä valinnaisia?

Materiaalin muuntaminen Parhaassa tapauksessa prosessi voidaan tehdä koneellisesti Siirryttäessä muotoillusta rakenteiseen tekstiin, prosessi voi vaatia hyvin paljon tekstin manuaalista kopioimista Joskus prosessia voi nopeuttaa siirtymällä formaatista toiseen jonkun väliformaatin kautta (MS Word -> RTF -> XML)

Ohjelmistojen valinta ja ympäristön perustaminen Rakenteista tekstiä voidaan hallinoida monella tapaa: Rakenteista tekstiä varten suunniteltu sisällönhallintajärjestelmä Ohjelmistokehitykseen suunnattu versionhallintajärjestelmä Verkkolevy Maksullinen palvelu vs. avoin järjestelmä Julkaisujärjestelmä Maksullinen järjestelmä vs. avoin järjestelmä Kirjoitusympäristö Tietokantaan kiinteästi liittyvä tai erillinen työkalu

Käyttäjien kouluttaminen Rakenteisessa ympäristössä kirjoittaminen voi valituista työkaluista riippuen poiketa erittäin paljon muotoiltuun tekstiin perustuvasta ympäristöstä muutosvastarinta Työkalukoulutuksen lisäksi tärkeää esittää uudesta ympäristöstä saatavat hyödyt Kirjoitustyökalut kehittyneet huimasti käyttäjäystävällisempään suuntaan

Mitä samaa kuin muotoillun tekstin käytössä? Rakenteinen ohjeteksti voi noudattaa perinteistä dokumentointimallia: Yksi ohjeteksti– yksi tiedosto Yksi ohjeteksti– yksi kirjoittaja Kirjoitusprosessi voi olla varsin samankaltainen: Materiaalin hankinta > Tekstien laatiminen > Tekstien katselmointi > Katselmointikorjaukset > Hyväksyminen > Julkaisu

Miten eroaa muotoillun tekstin käytöstä? Ohjeteksteihin on helpompi lisätä tiedoston ulkopuolista materiaalia ja sisällön rajaaminen on helpompaa Ohjetekstejä on helpompi käsitellä koneellisesti Julkaisu eri muodoissa suoraviivaisempaa Suurtenkin ulkoasumuutosten tekeminen nopeaa Kirjoitettaessa modulaarisia ohjetekstejä yhdellä ohjetekstillä on tyypillisesti monta kirjoittajaa Ohjetekstejä ei välttämättä katselmoida kokonaisuuksina

Miten eroaa muotoillun tekstin käytöstä? Hypertekstimuotoisten ohjetekstien välille on helppo tehdä linkkejä Käyttäjän ei tarvitse lukea ohjetekstejä lineaarisesti Käyttäjä löytää tarvitsemansa tiedon nopeammin Dokumenttityypit saattavat muuttua kaikki-yhdessä-paketissa –mallista erikoistuneimmiksi ohjeteksteiksi

Rakenteinen teksti kirjoittajan kannalta Rakenteiseen tekstiin siirtyminen voi olla työlästä, jos kirjoittajat ovat tottuneet perinteiseen kirjoitusmalliin: Uudet kirjoitustyökalut Uusia tapoja tehdä virheitä Uudet työskentelytavat Joitakin ”virheitä” ei pysty korjaamaan itse Sisällönhallintajärjestelmät Versionhallinta, rinnakkaiset julkaisut ja dokumenttiversiot Tiedonhaku yleensä helpompaa

Rakenteinen teksti: Edut Tekstin koneellinen käsittely ja tietokantahaut helpottuvat Useiden julkaisuformaattien käyttö helpottuu ja julkaisujen laatiminen nopeutuu Kirjoittajat voivat keskittyä sisältöön Kun järjestelmä määrittää ulkoasun ja rakenteen, dokumenttien ulkoasu pysyy standardinmukaisena Sisältö ei ole riippuvainen mistään tietystä käyttöjärjestelmästä tai ohjelmasta

Rakenteinen teksti: Haasteet Rakenteiseen tekstiin siirtyminen on kallis ja aikaavievä prosessi Järjestelmän perustaminen ja ylläpito on vaativaa, sekä vaatii merkittävän taloudellisen panostuksen, jos työ ostetaan organisaation ulkopuolelta Rakenteiseen kirjoitusympäristöön siirtyminen voi vaatia paljon koulutusta

Yhteenveto Rakenteinen teksti kuvailee tekstin sisältöä ja rakennetta Rakenne-elementtejä merkitään tagien avulla DTD on rakenteisen dokumentin kielioppi Rakenteisuus helpottaa tekstin koneellista käsittelyä → kustannussäästöt Rakenteisuus mahdollistaa useiden julkaisuformaattien käytön Siirtyminen WYSIWYG-dokumentaatiosta rakenteiseen voi olla hyvin kallista ja aikaavievää

Harjoitus Tarkastele seuraavaa ohjesivua: http://mikahimself.com/TECHS6/lecture-1-homework.png Pohdi mitä elementtejä sivun sisällön esittämiseen tarvitaan? Mieti, mitä osia sivun sisällöstä voitaisiin tuottaa ainakin osittain koneellisesti tai automaattisesti Laadi lista tarvittavista elementeistä Palautus: mika.laihanen@gmail.com [otsikkoon teksti TECHS6]