1 / 28

Rakenteinen dokumentaatio ja DITA

Rakenteinen dokumentaatio ja DITA. 20.11.2018. Sisältölainat. Sisältölainoilla tarkoitetaan pienten tekstiosioiden tai esim. kuvien kopioimista alkuperäisestä moduulista toiseen moduuliin

dgirard
Download Presentation

Rakenteinen dokumentaatio ja DITA

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. Rakenteinen dokumentaatio ja DITA 20.11.2018

  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: <noteconref="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 <step id="play"> <cmd>Tap Play to listen to music</cmd> </step> <step> <cmd>Tap Stop to stop the music</cmd> </step> 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 <step id="play"> <cmd>Tap the Music Player icon.</cmd> </step> <step> <cmd>TapStream.</cmd> </step> <step> <cmd>Select a stream source.</cmd> </step> <step id="play-end"> <cmd>TapPlay.</cmd> </step> <step> <cmd>TapStop to stop streaming</cmd> </step> Teksti, johon lainataan <step conref="play.music.dita#play.music/play" conrefend="play.music.dita#play.music/play-end" > <cmd>Dowhatever.</cmd> </step> <step> <cmd>Enjoythemtunes.</cmd> </step> Julkaistu teksti • Tap the Music Player icon • Tap Stream. • Select a stream source. • Tap Play. • Enjoythemtunes.

  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<phconref="ui.dita#ui/Quit"/> to closethe application.</cmd> </step> <step> <cmd>Click<phconref="ui.dita#ui/Next"/> to continue.</cmd> </step>

  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: <topicrefkeyref="mc.intro" /> <xrefkeyref="mc.intro" />

  19. Tunnisteet • Tunnisteita voi käyttää myös viitattaessa moduulien sisällä oleviin elementteihin: <xrefkeyref="mb.intro#mb.introduction/stuff" /> • Myös sisältölainat voi tehdä tunnisteiden avulla. Tällöin conref-attribuutti vaihtuu conkeyref-attribuutiksi: <noteconkeyref="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 laaditohjeensuomeksi, käytä “englanninkielisten” moduulienotsikoissa – eli title-elementissä – tunnistetta EN-US. Vaihdamyösxml:langattribuutinarvo, jottaautomaattisestiluoduttekstittulostuvatenglanniksijulkaistussamateriaalissa

  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 • 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: • 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 mika.laihanen+techs6@gmail.com otsikolla TECHS6-lopputyö. Palauta paketti viimeistään 23.12.2018.

  28. Kurssipalaute • Kurssipalautteen voit täyttää osoitteessa http://mikahimself.com/TECHS6/Palaute/ • 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.

More Related