Rakenteinen dokumentaatio ja DITA

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

1 Rakenteinen dokumentaatio ja DITA

2 Julkaisujen koostaminen

3 DITA Map DITA Map on moduulityyppi, jonka avulla yksittäiset moduulit voidaan järjestää haluttuun järjestykseen ja luoda tekstiin otsikkotasoja Käytännössä DITA Map –moduuli sisältää linkkejä toisiin moduuleihin

4 DITA Map - Käyttökohteita
DITA Map -moduuleja voi käyttää sisällön suunnitteluun DITA Map -moduulien avulla voi julkaista useamman kuin yhden moduulin kerrallaan DITA Map -moduulien avulla ohjeteksti voidaan rakentaa useassa osassa Ehdollistamalla DITA Map –moduulin sisältöä, samasta rungosta voi koota monta erilaista julkaisua eri julkaisukanaviin

5 DITA Map - Otsikointi DITA Map –moduuleissa voi käyttää vain yhtä otsikkoelementtiä Jos julkaistavissa ohjeteksteissä halutaan käyttää useaa erilaista otsikkoa, otsikot voi luoda ehtojen avulla: <title> <ph product="MBX210">Otsikko 1</ph> <ph product="MBX280">Otsikko 2</ph> </title>

6 DITA Map: Metatieto DITA Map-moduuliin voi lisätä myös metatietoa:
Ohjetekstin julkaisija Ohjetekstin kirjoittaja Julkaisupäivä DITA Mapissa ei ole prolog-elementtiä, vaan metatieto kirjoitetaan topicmeta-elementin alle

7 DITA Map – Sisällön rakentaminen
DITA Map-moduuleissa sisältö koostuu pääasiassa topicref-elementin avulla luoduista linkeistä. Linkin kohde merkitään xref-elementin tapaan href-attribuuttiin topicref-elementtejä voi sijoittaa moduuliin sisäkkäin

8 DITA Map – Sisällön rakentaminen
<topicref href="paataso1.dita"> <topicref href="1-alataso1.dita" /> <topicref href="1-alataso2.dita"> <topicref href="2-alataso1.dita"> <topicref href="3-alataso1.dita" /> </topicref> <topicref href="paataso2.dita" />

9 DITA Map – Sisällön rakentaminen
Tekstiin voi luoda väliotsikoita topichead-elementillä. Otsikkoteksti kirjoitetaan tässä tapauksessa navtitle-elementtiin tai navtitle-attribuuttiin: <topichead> <topicmeta><navtitle>Troubleshooting Stuff</navtitle></topicmeta> <topicref href="troubleshooting-module1.dita" /> <topicref href="troubleshooting-module2.dita" /> </topichead> <topichead navtitle="Troubleshooting Stuff">

10 DITA Map – Sisällön rakentaminen
Toisiinsa olennaisesti liittyviä ja aina yhdessä esiintyviä tekstin osia voi ryhmitellä topicgroup-elementin alle. Topicgroup-elementti ei vaikuta julkaistavan tekstin rakenteeseen. <topicgroup> <topicref href=”related-stuff1.dita" /> <topicref href=”related-stuff2.dita" /> </topicgroup>

11 DITA Map Koosta laatimistasi moduuleista julkaisu DITA Map –moduulin avulla Järjestele moduulit selkeään järjestykseen niin, että eri informaatiotyypit (kuvat, moduulit, jne.) ovat omissa hakemistoissaan. Huomaa, että DITA Map –moduulin tulee olla hakemistorakenteen juuritasolla, että julkaisut onnistuvat kaikissa tapauksissa.

12

13 DITA Bookmap

14 DITA Bookmap DITA Bookmap -moduulien avulla moduuleista voi koota laajoja, kirjamuotoisia julkaisuja Sen lisäksi, että moduuleille voi luoda kappalejaon, DITA Bookmap -moduuli mahdollistaa myös johdanto-, sisällysluettelo-, ja kuvaluettelosivujen lisäämisen julkaistavaan tekstiin

15 DITA Bookmap - Otsikointi
DITA Bookmap-moduulien otsikot sijoitetaan booktitle-elementin sisälle Ensisijainen otsikko kirjoitetaan mainbooktitle-elementtiin ja vaihtoehtoinen otsikko booktitlealt-elementtiin Vaihtoehtoisia otsikoita voi luoda lisää ehtoja käyttämällä

16 DITA Bookmap - Metatieto
DITA Bookmap-moduulien metatieto sijoitetaan bookmeta-elementin alle. DITA Bookmapissa on huomattavasti laajempi valikoima metatietoelementtejä kuin tavallisissa topic-moduuleissa ja DITA Map -moduuleissa

17 DITA Bookmap - Metatieto
Elementti Kuvaus linktext Bookmapiin viittaavan linkin teksti searchtitle XHTML-sivun otsikkoteksti shortdesc Julkaisun lyhyt kuvaus Tekijän nimi (ja mahd. kuvaus) authorinformation Tekijän tiedot authorinformation/organizationinfo Tekijäorganisaation tiedot authorinformation/organizationinfo/namedetails/organizationnamedetails Tekijäorganisaation nimitiedot (Kirjoitetaan lapsielementtien sisään) authorinformation/organizationinfo/addressdetails Tekijäorganisaation osoitetiedot (Lapsielem.) authorinformation/organizationinfo/contactnumbers Tekijäorganisaation puhelinnumerot (Lapsielem.) authorinformation/organizationinfo/ addresses Tekijäorganisaation sähköpostiosoitteet (Lapsielem.) authorinformation/organizationinfo/urls Tekijäorganisaation kotisivut (Lapsielem.)

18 DITA Bookmap - Metatieto
Elementti Kuvaus authorinformation/personinfo Kirjoittajan tiedot authorinformation/personinfo/namedetails/personname Kirjoittajan nimitiedot (Kirjoitetaan lapsielementtien sisään) authorinformation/personinfo/addressdetails Kirjoittajan osoitetiedot (Lapsielem.) authorinformation/personinfo/contactnumbers Kirjoittajan puhelinnumerot (Lapsielem.) authorinformation/personinfo/ addresses Kirjoittajan sähköpostiosoitteet (Lapsielem.) source Tekstin lähde/lähteet publisherinformation Julkaisijan tiedot publisherinformation/person Julkaisijan nimi (jos henkilö) publisherinformation/organization Julkaisijan nimi (jos yritys/organisaatio) publisherinformation/printlocation Painopaikka publisherinformation/published Julkaisuaika

19 DITA Bookmap - Metatieto
Elementti Kuvaus prodinfo/prodname, prodinfo/vrmlist Tuotteen tietoja (ks. Topic -elementin metatiedot) bookid/bookpartno Julkaisun osanumero bookid/edition Julkaisun painos bookid/isbn Julkaisun ISBN bookrights/copyrfirst/year Tekijänoikeuden alkuvuosi bookright/copyrlast/year Tekijänoikeuden loppuvuosi bookright/bookowner/organization Tekijänoikeuksien haltija (jos yritys/organisaatio) Bookright/bookowner/person Tekijänoikeuksien haltija (jos henkilö)

20 DITA Bookmap - Metatieto
Tekstiä julkaistaessa DITA Bookmapiin tallennettujen metatietojen avulla julkaisujen kansilehtiin lisätään monesti yritysten osoitetietoja ja tekstin tekijänoikeustiedot DITA Bookmap -moduulin metatietoja voi käyttää myös joissakin sisällönhallintajärjestelmissä hakutoimintojen tukena

21 DITA Bookmap - Johdanto
Ennen varsinaista sisältöä esitettävä tieto – esim. sisällysluettelo, taulukkoluettelo, johdantokappale – merkitään frontmatter-elementin sisälle Sisältö, jonka DITA OT –luo automaattisesti, kirjataan booklists-elementin alle

22 DITA Bookmap - Johdanto
<frontmatter> <booklists> <toc /> <figurelist /> <tablelist /> </booklists> </frontmatter> Luo automaattisesti sisällysluettelon Luo listan kuvista Luo listan taulukoista

23 DITA Bookmap - Johdanto
Tiivistelmä julkaisun sisällöstä voidaan merkitä bookabstract-elementtiin Jos julkaisussa on johdantokappale, joka esim. esittelee julkaisun rakenteen, voidaan se merkitä preface-elementtiin

24 DITA Bookmap - Johdanto
<frontmatter> <booklists> <toc /> <figurelist /> <tablelist /> </booklists> </frontmatter> <bookabstract href="GreatAbs.dita"/> <preface href="myPreface.dita" /> Luo automaattisesti sisällysluettelon Luo listan kuvista Luo listan taulukoista

25 DITA Bookmap - Sisältö DITA Bookmap voi sisältää DITA Mapin tavoin viittauksia moduuleihin. Päätason viittaukset – eli ohjetekstin luvut – laaditaan chapter-elementin avulla. Myös chapter-elementeissä moduuli, johon viitataan, kirjataan href-attribuuttiin: <chapter href="moduuli.dita">

26 DITA Bookmap - Sisältö Chapter-elementtejä voi käyttää myös pelkästään otsikkotasona Tällöin chapter-elementtiin ei lisätä viittausta moduuliin, vaan pelkkä otsikko navtitle-attribuutin tai navtitle-elementin avulla: <chapter navtitle="You’ll Never Believe What This Chapter Contains"/> <chapter> <topicmeta> <navtitle>5 Amazing DITA Feature You Won’t Believe Exist!</navtitle> </topicmeta>

27 DITA Bookmap - Sisältö Osat, joista luvut koostuvat, merkitään topicref-elementin avulla. Topicref-elementtien avulla luodaan lukujen sisäinen hierarkia – chapter-elementtejä voi käyttää vain päätasolla Chapter-elementti ei voi sisältää toista chapter-elementtiä

28 DITA Bookmap - Sisältö <chapter href="introduction.dita">
<frontmatter> <booklists> … </booklists> </frontmatter> <bookabstract href="GreatAbs.dita"/> <preface href="myPreface.dita" /> <chapter href="introduction.dita"> <topicref="productInfo.dita"/> <topicref="background.dita"/> </chapter> <chapter href="moreStuff.dita">

29 DITA Bookmap - Sisältö Jos ohjeteksti on laaja, Bookmap-moduulista voi tulla hyvin pitkä Moduulin kokoa voi rajoittaa koostamalla ohjeteksin luvut DITA Map –moduuleihin ja viittaamalla niihin Bookmap-moduulista Tällöin DITA-OT:lle täytyy ilmoittaa, että kohde johon viitataan, on DITA Map -moduuli: <chapter href="mappi.ditamap" format="ditamap" />

30 DITA Bookmap - Sisältö <chapter href="introduction.dita">
<frontmatter> <booklists> … </booklists> </frontmatter> <bookabstract href="GreatAbs.dita"/> <preface href="myPreface.dita" /> <chapter href="introduction.dita"> <topicref="productInfo.dita"/> </chapter> <chapter href="moreStuff.ditamap" format="ditamap"/> <chapter href="instructions.dita"> <topicref href="how.to.do.stuff.dita"/>

31 DITA Bookmap Koosta laatimistasi moduuleista kahvinkeittimen käyttöohje DITA Bookmap-moduulityypin avulla. Miten DITA Bookmap-julkaisu eroaa DITA Map julkaisusta?

32 Ehdot ja uudelleenkäyttö

33 Uudelleenkäyttö Yksinkertaisin tapa käyttää sisältöä uudelleen on yhden moduulin käyttö useassa eri julkaisussa Suora uudelleenkäyttö ei aina ole mahdollista tuotteiden eroavaisuuksien vuoksi, eikä moduulin koko sisällön käyttäminen uudelleen ole aina perusteltua DITA-moduulien sisältöä voi ehdollistaa uudelleenkäytettäväksi ja DITA-moduuleihin voi lainata sisältöä toisista moduuleista

34 Ehtojen käyttäminen Moduuleista voidaan ehdollistaa esim.: Tuotenimiä
Tiettyyn tuotteeseen viittaavia tekstikappaleita Viittauksia tietyn tuotteen ominaisuuksiin (esim. tuotteen ominaisuuksia esittelevillä listoilla) Tuotekuvia

35 Ehtojen käyttäminen Ehtoja käyttämällä ohjetekstin sisältöä voidaan muokata niin että se sopii erilaisiin julkaisuihin Ehtoja hallitaan ehtoattribuuttien ja niiden arvojen avulla Ehtoattribuutteja ovat audience, platform, product, otherprops ja rev

36 Ehtojen käyttäminen Pääasiassa sisällön hallitsemiseen käytetään attribuutteja audience, platform ja product Audience-attribuutilla merkitään haluttua kohdeyleisöä (esim. Administrator) Platform-attribuutilla merkitään tuotealustaa (esim. Windows) Product-attribuutilla merkitään tuotetta (esim. iPhone6S)

37 Ehtojen käyttäminen Otherprops-attribuuttia voidaan käyttää muiden attribuuttien tarkenteena. Kaikki DITA-prosessorit eivät erottele sisältöä pelkästään otherprops-attribuutin perusteella: <p platform="windows" otherprops="xp">…</p> Rev-attribuuttia käytetään ainoastaan sisällön korostamiseen (vaatii julkaisuympäristön tuen)

38 Ehtojen käyttäminen Julkaisuehto määritetään lisäämällä haluttuun elementtiin joku ehtoattribuuteista, ja ehtoa kuvaava arvo: <p platform="windows">Windows specific stuff</p> <li product="mbX210">MoccaBlaster X210 -lista</li> <table audience="Admin"> <chapter platform="windows" audience="Admin">

39 Vaihtoehtoisia lähestymistapoja
Sisällön ehdollistaminen moduulitasolla ei ole pakollista: Joka tuotteelle voi tehdä oman moduulinsa ja ehdollistaa tuotekohtaiset moduulit Bookmap/DITA Map –tasolla Jokaiselle tuotteelle voi laatia täysin omat moduulit ja Bookmapit/DITA Mapit

40 Ehdollistamisen etuja
Ylläpidettävän materiaalin määrä on yleensä pienempi – yksi yhteinen BookMap usean rinnakkaisen sijaan Moduulimäärä pienempi - käännettävän materiaalin määrä pienempi

41 Ehdollistetun materiaalin julkaiseminen
Julkaisuun sisällytettävät ehdot määritetään DITAVAL-tiedostossa. Jos materiaalia ei ole määritetty jätettäväksi pois, DITA-OT poimii materiaalin julkaisuun mukaan <val> <prop att="audience" val="administrator" action="exclude“/> <prop att="product" val="acmephone5" action="exclude"/> <prop att="product" val="acmephone4" action="include"/> </val>

42 Ehdollistetun materiaalin julkaiseminen
Kun julkaisutyökalu käynnistetään, työkalu käy läpi kaikki elementit, jotka on merkitty ehdolla Jos ehto on määritetty sisällytettäväksi julkaisuun tai ehtoa EI ole mainittu DITAVAL-tiedostossa, se sisällytetään julkaisuun Muussa tapauksessa, sisältö jätetään pois julkaisusta

43 Ehdollistetun materiaalin julkaiseminen
DITAVAL-tiedoston voi laatia itse ja lisätä sen parametrina DITA-OT –julkaisuun Useimmissa kirjoitusohjelmissa on työkalu, jonka avulla käyttäjä voi laatia DITAVAL-tiedoston Oxygenissa julkaisuehdot määritellään DITA Maps Manager -näkymän kautta.

44

45 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

46 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

47 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

48 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

49 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

50 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

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

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

53 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

54 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 ohjeteksissä käytettävät varoitukset, huomautukset ja vinkiti siihen. Liitä käyttämäsi varoitukset, huomautukset ja vinkit tekstiin conref-attribuutin avulla