Rakenteinen dokumentaatio ja DITA

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

1 Rakenteinen dokumentaatio ja DITA

2 Sisältölainat Sisältölainoilla tarkoitetaan pienten tekstiosioiden tai esim. kuvien kopioimista alkuperäisestä moduulista toiseen moduuliin Sisältölainoja käytetään erityisesti sellaisissa tapauksissa, joissa sisältö toistuu samanlaisena useassa eri moduulissa

3 Sisältölainat Sisältölainat laaditaan conref-attribuutilla
Tekstiin lisätään ensin lainattava elementti, ja lainan lähde merkitään elementtiin conref-attribuutilla: <note conref="notes.dita#notes/borrowedNote"/> Lainattavan elementin tyyppi Moduuli, josta lainataan Moduulin tunnus Lainattavan elementin tunnus

4 Sisältölainat Sisältölainan lopullinen sisältö määritetään aina julkaisuvaiheessa Vaikka lainattu kohta olisi kirjoitusvaiheessa oikeanlainen, voi alkuperäisen moduulin kirjoittaja muuttaa tekstiä ennen julkaisua Lainauksia kannattaa tehdä vain moduuleista, joiden sisältö muuttuu harvakseltaan ja kontrolloidusti

5 Sisältölainat Huomautukset ja varoitukset, jotka toistuvat samanlaisina kaikissa dokumenteissa, toteutetaan monesti sisältölainojen avulla Näin sisältö pysyy samanlaisena kaikissa julkaisuissa, ja sisältömuutokset tarvitsee tehdä vain yhteen paikkaan - kirjastomoduuliin

6 Sisältölainat Sisältölaina voi olla myös usein toistuva osa jotain tehtävää Ohje, jolla käyttäjä pääsee tiettyyn käyttöliittymän osaan, voidaan kirjoittaa kerran, ja lainata sisältö kaikkiin niihin ohjemoduuleihin, joissa käyttäjän täytyy siirtyä kyseiseen käyttöliittymän osaan

7 Sisältölainat Alkuperäinen teksti Teksti, johon lainataan
<step id="play"> <cmd>Tap Play to listen to music</cmd> </step> <step> <cmd>Tap Stop to stop the music</cmd> Teksti, johon lainataan <step conref="play.music.dita#play.music/play" > <cmd>Play that funky music.</cmd> </step> Julkaistu teksti: 1. Tap play to listen to music.

8 Sisältölainat Jos laina on osa jotain tehtävää, lainan ei tarvitse rajoittua vain yhteen step-elementtiin Jos tekstistä halutaan lainata useampi peräkkäinen step-elementti, lainan päättymiskohdan voi merkitä conrefend-attribuutilla Tällöin kohdemoduuliin lainataan kaikki step-elementit alkupisteestä siihen step-elementtiin asti, jossa on conrefend-attribuuttia vastaava tunniste

9 Sisältölainat Alkuperäinen teksti Teksti, johon lainataan
<step id="play"> <cmd>Tap the Music Player icon.</cmd> </step> <step> <cmd>Tap Stream.</cmd> <cmd>Select a stream source.</cmd> <step id="play-end"> <cmd>Tap Play.</cmd> <cmd>Tap Stop to stop streaming</cmd> Teksti, johon lainataan <step conref="play.music.dita#play.music/play" conrefend="play.music.dita#play.music/play-end" > <cmd>Do whatever.</cmd> </step> <step> <cmd>Enjoy them tunes.</cmd> Julkaistu teksti Tap the Music Player icon Tap Stream. Select a stream source. Tap Play. Enjoy them tunes.

10 Sisältölainat ja kääntäminen
Käyttöliittymiä dokumentoitaessa on tärkeää, että käyttöliittymän osien nimet on käännetty oikein Jos käyttöliittymän osien nimet – esim. näyttöjen nimet ja painikkeiden tekstit – kootaan kirjastomoduuliin, voidaan varmistua siitä että termit säilyvät yhtenäisinä koko ohjetekstissä

11 Sisältölainat ja kääntäminen
<step> <cmd>Click <ph conref="ui.dita#ui/Quit"/> to close the application.</cmd> </step> <cmd>Click <ph conref="ui.dita#ui/Next"/> to continue.</cmd>

12 Sisältölainat ja kääntäminen
Jos käyttöliittymätekstit ja kirjastomoduuli käännetään samaan aikaan, on helppo varmistua että molemmissa käytetään samoja käännöksiä Näin vältytään siltä, että eri kääntäjät kääntävät termejä eri tavalla

13 Kääntäminen – Moduulin kieli
Moduulin kieli vaikuttaa DITAn käyttämien automaattisesti generoitavien tekstien kieleen Moduulin kieli asetetaan juurielementin xml:lang –attribuutin avulla Jos moduulin xml:lang –attribuuttia ei ole määritetty, DITA olettaa että moduulin kieli on englanti

14 Harjoitus: Sisältölainat
Käännöskustannusten karsimiseksi MoccaBlaster-kahvinkeitinten varoitukset, huomautukset ja vinkit päätetään koota erilliseen moduuliin, joista niitä voidaan lainata tarvittaviin paikkoihin Laadi kirjastomoduuli ja kokoa ohjetekstissä käytettävät varoitukset, huomautukset ja vinkit siihen. Liitä käyttämäsi varoitukset, huomautukset ja vinkit tekstiin conref-attribuutin avulla

15 Tunnisteet Jos ohjetekstissä käytetään paljon lainoja, linkkejä ja kuvia, tiedostopolkujen muuttuminen voi aiheuttaa paljon muutoksia moduuleihin Tiedostopolkujen muutoksista aiheutuvat muutostyöt voi minimoida tunnisteiden avulla

16 Tunnisteet Jotta tunnisteita voi käyttää, täytyy ne ensin määritellä DITA Map- tai DITA Bookmap -dokumentissa Tunnisteet määritetään samalla kun tiedostoon lisätään viittaus johonkin moduuliin: <chapter href="topics/info.dita keys="info" /> <topicref href="images/kuva.png" keys="kuva" /> <topicref href="libs/notes.dita" keys="notes" />

17 Tunnisteet Tunnisteiden ansiosta tiedoston sijainti täytyy määrittää vain kerran Jos tiedoston sijainti muuttuu, riittää että hakemistopolku korjataan uudeksi kohdassa, jossa tunniste on määritetty

18 Tunnisteet Kun tunniste on määritetty DITA Map- tai DITA Bookmap-tiedostossa, muista moduuleista voi viitata tunnistetiedostossa määritettyihin moduuleihin tunnisteen avulla href-attribuutin sijaan viittaus luodaan keyref-attribuutin avulla: <topicref keyref="mc.intro" /> <xref keyref="mc.intro" />

19 Tunnisteet Tunnisteita voi käyttää myös viitattaessa moduulien sisällä oleviin elementteihin: <xref keyref="mb.intro#mb.introduction/stuff" /> Myös sisältölainat voi tehdä tunnisteiden avulla. Tällöin conref-attribuutti vaihtuu conkeyref-attribuutiksi: <note conkeyref="mb.intro#mb.introduction/my-note" />

20 Lopputyö

21 Lopputyö MoccaBlaster-yhtiö julkaisee uuden, mullistavan kahvinkeittimen, joka perustuu aiempaan, MoccaBlaster X210 –malliin Laadi uuden keitinmallin käyttöohje suomeksi ja englanniksi(*) siten, että käytät hyväksesi mahdollisimman paljon aiempaa mallia varten laadittua materiaalia * Jos laadit ohjeen suomeksi, käytä “englanninkielisten” moduulien otsikoissa – eli title-elementissä – tunnistetta EN-US. Vaihda myös xml:lang attribuutin arvo, jotta automaattisesti luodut tekstit tulostuvat englanniksi julkaistussa materiaalissa

22 Lopputyö MoccaBlaster EX2000 –malli sisältää kaikki samat ominaisuudet kuin X210. Tämän lisäksi: Kahvinkeittimen runko on uudistunut. Keittimen mukana toimitetaan ionisoitu adamantium-alusta, joka takaa kahvin täyteläisen maun. Adamantiumia ei saa viedä YK:n taloussaarron alaisiin maihin, joten ohjetekstin tulee sisältää huomautus tästä

23 Lopputyö MoccaBlaster EX2000 -keittimen voi liittää langattomaan verkkoon, jolloin kahvinkeittimen voi käynnistää esim. internetselaimen avulla. Laadi ohje, jossa kerrotaan kuinka keitin liitetään langattomaan verkkoon Laadi ohje, jossa kerrotaan kuinka keitin käynnistetään selaimen avulla Huomauta käyttäjälle että internet-käytöstä voi aiheutua kustannuksia Jos internetyhteys ei toimi, yhteyden voi nollata painamalla keittimen pohjassa olevaa reset-nappia. Keitin sisältää puhesyntetisaattorin, joka huomauttaa käyttäjää kahvin kuumuudesta kahvia kaadettaessa. Tämän mallin käyttäjiä ei siis erikseen tarvitse varoittaa kahvin kuumuudesta!

24 Lopputyö Järjestele molempien ohjetekstien (x210 ja EX2000) moduulit, kuvat ja DITA Bookmap-tiedostot (ja mahdolliset DITA Map –tiedostot) kansioihin niin, että materiaalit on selkeästi jaoteltu, eivätkä eri kieliversioiden moduulit mene keskenään sekaisin Laadi DITA Bookmap-tiedostot, joista julkaisut tehdään. Voit joko laatia joka julkaisuversiolle oman DITA Bookmap-tiedoston, tai käyttää yhtä DITA Bookmap-tiedostoa kaikkien julkaisujen pohjana

25 Lopputyö - sisältö MB X210 MB EX2000 Keittimen esittely
Keittimen tekniset tiedot Kahviterminologia Osaluettelo Ongelmanratkaisuohjeet Kahvinkeitto-ohjeet Puhdistusohje MB EX2000 Keittimen esittely Keittimen tekniset tiedot Kahviterminologia Osaluettelo Ongelmanratkaisuohjeet Kahvinkeitto-ohjeet Puhdistusohje Ohje keittimen liittämisestä langattomaan verkkoon Ohje keittimen käynnistämisestä selaimen avulla

26 Lopputyö - sisältö Ohjeessa tulee olla myös: Ohjeessa voi olla:
Sisällysluettelo Luettelo kuvista Luettelo taulukoista Ohjeessa voi olla: Sanasto

27 Lopputyö Paketti on valmis kun kaikki ohjeversiot (x210 fi tai en, ex2000-en, ex2000-fi) voi julkaista laatimiesi bookmap-tiedostojen avulla PDF-muodossa. Paketoi koko kansiorakenne zip-pakettiin ja lähetä se osoitteeseen otsikolla TECHS6-lopputyö. Palauta paketti viimeistään

28 Kurssipalaute Kurssipalautteen voit täyttää osoitteessa Laita rasteja ruutuun ja kerro omin sanoin mikä toimi ja mikä ei. Jos jokin asia ei toiminut alkuunkaan, kerro miten sen voisi tehdä mielestäsi paremmin.