Rakenteinen dokumentaatio ja DITA 16 12 2014 Sislln

Rakenteinen dokumentaatio ja DITA 16. 12. 2014

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

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

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

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

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

Sisältölainat o Sisältölaina voi olla myös usein toistuva osa jotain tehtävää o 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

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

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

Sisältölainat ja kääntäminen o Käyttöliittymiä dokumentoitaessa on tärkeää, että käyttöliittymän osien nimet on käännetty oikein o 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ä

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

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

Sisältölainat o Käännöskustannusten karsimiseksi Mocca. Blasterkahvinkeitinten varoitukset, huomautukset ja vinkit päätetään koota erilliseen moduuliin, joista niitä voidaan lainata tarvittaviin paikkoihin o 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

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

Tunnisteet o Tunnisteiden käyttämiseksi on ensin luotava DITA Map –tiedosto o 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” />

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

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

Tunnisteet o 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"/> o Viittauksessa määritetään, että kyseessä on DITA Map –tiedosto, ja että tiedostoa käytetään vain resurssina

Tunnisteet o Tämän jälkeen Bookmap-tiedostosta ja muista moduuleista voi viitata tunnistetiedostossa määritettyihin moduuleihin tunnisteen avulla o href-attribuutin sijaan viittaus luodaan keyrefattribuutin avulla: <topicref keyref="mc. intro" /> <xref keyref="mc. intro" />

Tunnisteet o Tunnisteita voi käyttää myös viitattaessa moduulien sisällä oleviin elementteihin: <xref keyref="mb. intro#mb. introduction/stuff" /> o 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" />

Tunnisteet o Tunnistetiedostossa voi käyttää ehtoja, jos haluaa suodattaa sisältöä ehtojen perusteella: <keydef href=". . /moduuli. dita" keys="moduuli" audience="novice"/> <keydef href=". . /expertti-moduuli. dita" keys="moduuli" audience="expert"/>

Lopputyö

Lopputyö • Mocca. Blaster-yhtiö julkaisee uuden, mullistavan kahvinkeittimen, joka perustuu aiempaan, Mocca. Blaster X 210 –malliin • Laadi uuden keitinmallin käyttöohje suomeksi tai englanniksi(*) siten, että käytät hyväksesi mahdollisimman paljon aiempaa mallia varten laadittua materiaalia * Käytä “englanninkielisten” moduulien otsikoissa – eli titleelementissä – tunnistetta EN-US

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

Lopputyö o Keittimen voi liittää langattomaan verkkoon, jolloin kahvinkeittimen voi käynnistää esim. internetselaimen avulla. o o 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. o Keitin sisältää puhesyntetisaattorin, joka huomauttaa käyttäjää kahvin kuumuudesta kahvia kaadettaessa. Käyttäjää ei siis erikseen tarvitse varoittaa kahvin kuumuudesta

Lopputyö o Järjestele molempien ohjetekstien (x 210 ja EX 2000) moduulit, kuvat ja map-tiedostot kansioihin niin, että materiaalit on selkeästi jaoteltu, eivätkä eri kieliversioiden moduulit mene keskenään sekaisin o Laadi bookmap-tiedostot, joista julkaisut tehdään. Voit joko laatia joka julkaisuversiolle oman bookmap-tiedoston, tai käyttää yhtä bookmaptiedostoa kaikkien julkaisujen pohjana

Lopputyö o Paketti on valmis kun kaikki ohjeversiot (x 210 fi, ex 2000 -en, ex 2000 -fi) voi julkaista laatimiesi bookmap-tiedostojen avulla PDF-muodossa. o Paketoi koko kansiorakenne zip-pakettiin ja lähetä se osoitteeseen mika. laihanen@gmail. com otsikolla TECHS 6 lopputyö. Palauta paketti viimeistään 16. 1. 2015.

Kurssipalaute o Kurssipalautteen voit täyttää osoitteessa http: //mikahimself. com/TECHS 6/Palaute/ o 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.