Rakenteinen dokumentaatio ja DITA

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

1 Rakenteinen dokumentaatio ja DITA

2 Julkaisujen koostaminen - Redux
DITA Bookmap on paras työkalu julkaistavan materiaalin koostamiseen Jos julkaistava materiaali on laaja ja sisältää lukuisia moduuleja, voi sisältöä jakaa DITA Map moduuleihin siten, että yksi DITA Map sisältää aina yhden julkaistavan luvun moduulit

3 Julkaisujen koostaminen - Redux
Sisällönhallintajärjestelmissä on usein julkaisutyökalu, jonka avulla yhdestä DITA Bookmap –tiedostosta voi julkaista sisältöä usealle kielelle Jos käytettävissä ei ole monikielisiä julkaisuja tukevaa järjestelmää, kannattaa joka kielelle luoda oma DITA Bookmap.

4 Sisällön ehdollistaminen
MoccaBlaster laajentaa markkina-aluettaan ja manuaaliin täytyy tehdä pieniä muutoksia: Muokkaa kahvinkeitto-ohjetta niin, että varoitus kuumasta kahvista näkyy ainoastaan Pohjois-Amerikan markkinoilla Lisää ympäristötietoista Eurooppaa varten suositus valkaisemattomien suodatinpussien käytöstä Julkaise molemmat ohjeet PDF-muodossa ja varmista että ehdot toimivat

5 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

6 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

7 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

8 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

9 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

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

11 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 you choose.</cmd> </step> <step> <cmd>Tap Produce Tunes.</cmd> Julkaistu teksti Tap the Music Player icon Tap Stream. Select a stream source. Tap Produce Tunes.

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

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

14 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

15 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

16 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

17 Tunnisteet Tunnisteiden käyttämiseksi on ensin luotava DITA Map –tiedosto Tässä tiedostossa määritetään julkaisussa käytettävät tiedostot ja tunnisteet, joilla niihin viitataan. <topicref href="../../moduuli.dita" keys="moduuli" /> <topicref href="../task-mod.dita" keys="task-mod" />

18 Tunnisteet Tunnistetiedoston ansiosta tiedoston sijainti täytyy määrittää vain kerran Jos tiedoston sijainti muuttuu, riittää että hakemistopolku muutetaan tunnistetiedostossa

19 Tunnisteet Jotta tunnisteita voisi käyttää julkaisussa, täytyy Bookmap-tiedostoon lisätä viittaus tunnistetiedostoon: <topicref href="Ditamaps/keydefs.ditamap" format="ditamap" processing-role="resource-only"/> Viittauksessa määritetään, että kyseessä on DITA Map –tiedosto, ja että tiedostoa käytetään vain resurssina

20 Tunnisteet Tämän jälkeen Bookmap-tiedostosta ja 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" />

21 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" />

22 Tunnisteet Tunnistetiedostossa voi käyttää ehtoja, jos haluaa suodattaa sisältöä ehtojen perusteella: <keydef href="../../FI/moduuli.dita" keys="moduuli-fi" audience="fi-FI"/> <keydef href="../../EN/moduuli.dita" keys="moduuli-en" audience="en-US"/>

23 Lopputyö

24 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

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

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

27 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

28 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

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

30 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

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