Rakenteinen dokumentaatio ja DITA

Esitys aiheesta: "Rakenteinen dokumentaatio ja DITA"— Esityksen transkriptio:

1 Rakenteinen dokumentaatio ja DITA

2 Mika Laihanen @mika_himself Käännöstiede (Englanti) 1999- Teknisen viestinnän ohjelma Technical Writer Documentation Technology Designer Systems Support Engineer Lead Documentation & Localization Specialist Citec Information Basware 2011-

3 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

4 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

5 Rakenteisuuden tasot

6 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)

7 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

8 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

9 <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>

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

11 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.

12 Muotoiltu teksti

13 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

14 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)

15 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

16 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)

17 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

18 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

19 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ää?

20 Rakenteinen teksti

21 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ä.

22 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 />

23 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>

24 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>

25 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>

26 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>

27 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

28 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ää

29 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>

30 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

31 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ä

32 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ä

33 Harjoitus: Rakenteinen teksti
Pohdi mitä elementtejä viereinen teksti sisältää? Voisivatko jotkin elementit sisältää myös attribuutteja? From: John Acronym To: Arthur Pewtey Date: 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

34 Rakenteisen tekstin käyttöönotto

35 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

36 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

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

38 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

39 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

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

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

42 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)

43 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

44 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

45 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

46 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

47 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

48 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

49 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

50 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

51 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ää

52 Harjoitus Tarkastele seuraavaa ohjesivua:
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: [otsikkoon teksti TECHS6]