12 Dokumenttiluokan toteuttamisesta

12 Dokumenttiluokan toteuttamisesta Tyypillisiä XML-sovellutuksia ovat esimerkiksi: - annettuun käyttötarkoitukseen räätälöity dokumenttityyppi (esim. painotalon BC malli käsikirjoituksen rakenteelle) - helppokäyttöinen, yhteensopiva ja muokattava tietorakenne (esim. ohjelman DEF talletustiedosto) - tietokannan GHI raporttitiedosto (joka esim. esitetään assosioimalla se valitun tyylimäärityksen kanssa asiakkaan selaimessa) Yhteistä näille on se, että viime kädessä XML-spesifikaation näkökulmasta niissä kaikissa on kyse jonkin tietyn dokumenttiluokan dokumenttien käsittelystä Lähes kaikille XML-sovellutuksille on yhteistä myös se, että niitä ei tehdä "XML:llä yksin XML:n takia", vaan koska - omassa sovelluksessa halutaan käyttää (jonkun muun suunnittelemaa) hyväksi havaittua dokumenttiluokkaa - dokumenttien rakenne halutaan tarkastaa tai validoida parserilla B 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 260

- dokumentteja halutaan välittää ohjelmien tai yhteisöjen C ja D välillä - dokumentteja halutaan katsella (prosessoida) ohjelmalla E - halutaan saada käyttöön XML-editori F, jne. Käytännössä tämä tarkoittaa sitä, että järkevän dokumenttiluokan suunnittelussa on kyse paljon enemmästä kuin vain merkkausdeklaraation suoltamisesta - kyse on siitä että - miten asiat kannattaisi määritellä & tehdä kun sovelluskenttä on tiedossa? - miten toiveet käytännössä voidaan pusertaa (esim.) DTD:n muotoon? Halutun dokumenttiluokan "tekeminen" tapahtuu "hyväksi havaitun käytännön" mukaisesti sisältäen esim. seuraavat vaiheet: a) esitutkimus (mitä tehdään/onnistuuko edes/mitä pitää tietää) b) määrittely (mitä ajetaan takaa/oleelliset tavoitteet) c) suunnittelu (miten tavoitteeseen päästään) d) toteutus (deklaraatioiden kirjoittaminen ja dokumentointi) e) testaus (toimiiko todella kuten ajateltiin/otetaanko käyttöön) 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 261

Dokumenttiluokan suunnittelu- ja kehitystyö vastaa siis itsessään suuresti dokumentaatioprosessia (pohjimmiltaanhan kyse samantyyppisestä asiasta) Pienissä sovellutuksissa vaiheet yleensä sulautuvat toisiinsa, eikä työn "muodollisista" vaiheista juuri välitetä. Systemaattisuuteen ja työvaiheiden tulosten selkeään kirjaamiseen on kuitenkin syytä kiinnittää erityistä huomiota (viimeistään) kun: - tilaus työlle tai tavoitteet tulevat työryhmän ulkopuolelta - työn asiasisältö tai tekemisen vastuualueet eivät ole kaikille tekijöille "itsestään selviä" - tekijätiimin koko kasvaa yli kolmen tai tekijät eivät työskentele "samassa tilassa" - tekijätiimin jäsenten osaamisalueet ovat selkeästi erilaisia - työn toteutuksen odotetaan kestävän yli viikon - joku muu käyttää työtä oman työnsä pohjana XML-sovellusten suunnitteleminen ei oleellisesti eroa muusta suunnittelu- ja toteutustyöstä myöskään siinä että: 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 262

- hyvä XML-spesifikaation (ja menetelmien) "tekninen" osaaminen ei pelasta suunnittelutyötä, mikäli sovellusalueen "sisällön" tuntemus on suunnittelijoilla heikkoa - mutta sopimattomat tekniset ratkaisut (ja XML:n ominaispiirteiden heikko tuntemus) saattavat "muuten hyvänkin" suunnitelman pilata (tai ainakin asettaa sille epärealistisia odotuksia) Käytännössä tämä tarkoittaa sitä, että sovelluksen Y suhteen pitää tietää mitä ollaan tekemässä, kenelle, miksi ja millä eväillä: 1) mihin sovellusta on tarkoitus käyttää ja mitä hyötyä XML:stä tässä yhteydessä on (tai uskotaan olevan)? 2) mihin olemassa oleviin järjestelmiin (tai dokumenttien tyyppimäärityksiin) ollaan sitoutumassa (tai kannattaisi sitoutua) ja mitä rajoituksia tai etuja tämä antaa suunnittelu- ja kehitystyölle (ja jatkossa käytölle)? 3) kuka tai mikä sovellusta käyttää ja miten ja kuinka tämä kaikki pitää ottaa huomioon dokumenttiluokan suunnittelussa, määrittelyssä, dokumentoinnissa, ohjeistuksessa (koulutuksessa) ja jatkokehityksessä? 4) kuinka paljon (ajallisia ja rahallisia) resursseja suunnittelu- ja kehitystyöhön on käytettävissä? Onko esim. omien editorien toteuttaminen mahdollista? 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 263

Puhtaasti XML 1.0:n näkökulmasta kysymykset kuitenkin pelkistyvät muotoon: "millaisia XML-dokumentteja sovelluksessa Y tarvitaan tai kannattaisi käyttää?" Tällöin dokumenttiluokan suunnitteleminen tarkoittaa konkreettisena toimenpiteenä dokumenttiluokan suunnittelemista, toteuttamista (esim. DTD:nä), dokumentoimista ja käytön ohjeistamista On kuitenkin syytä muistaa, että samalla tavalla kuin ohjelmointi (~"suorittavaa työtä") on vain osa ohjelmiston kehittämistyötä (~"suunnittelu- ja organisointityötä"), on dokumentin tyyppideklaraation kirjoittaminen vain osa dokumenttijärjestelmän kehitystyötä. Osa, johon ei tule ryhtyä liian varhain käytännössä ohjelmoinnista ja deklaraatioiden kirjoittamisesta kuitenkin puhutaan suunnittelua enemmän - syy on yleensä se, että näiden järkevä ohjeistaminen on yleisessä tapauksessa "helpompaa" tai "hyödyllisempää" Seuraavassa tarkastellaan lähinnä niitä (yksinkertaisia ja) konkreettisia menetelmiä, joita suunnittelutyöhön voidaan käyttää On ilmeistä, että halutun dokumenttiluokan suunnittelu, jatkuva testaus, ohjelmistovalinnat jne. kannattaa tehdä yhteistyössä sisällöntuottajien ja työn soveltavien tahojen kanssa (jos sellaisia on), käyttäjien taitotaso ja annettujen ohjelmistojen rajoitteet (yms.) huomioiden. Niinpä näistä asioista ei jatkossa joka yhteydessä enää erikseen mainita. 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 264

Kaiken suunnittelun kulmakivi: luova kokeileminen Suoraviivainen tapa lähteä liikkeelle dokumenttiluokan suunnittelussa on kirjoittaa kokeilumielessä halutuntyyppisiä (pienimuotoisia ja selkeitä) XMLdokumentteja (ilman dokumentin tyyppideklaraatiota): - perus"käsitteiden" tunnistaminen ja abstrahointi (elementtihierarkian pääpiirteiden suunnittelu mutta myös rakenteiden rajoittaminen) - geneeristen rakenteiden tunnistaminen (jos niitä oikeasti on) - elementtien tunnistaminen ja nimeäminen - keskustelun herättäminen suunnittelutiimin keskuudessa ja ideointi Elementtirakenteita suunniteltaessa kannattaa pitää sopiva tasapaino merkkauksen helppouden ja (sisällöllisen ja rakenteellisen) metatiedon määrän suhteen: - on totta, että yleisesti pätee: "mitä rikkaampi rakenne, sen parempi" - MUTT: mitä välttämättä tarvitaan? onko esim. metatietoa oikeasti runsaasti saatavilla, mistä se tulee ja tullaanko kaikki annetut täyttämään kentät systemaattisesti ja relevantilla tiedolla (onko mahdollista)? 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 265

Rakenteiden mutkikkuudessa, elementtien nimeämisessä yms. kannattaa myös etukäteen miettiä kuka elementit kirjoittaa ja millä: - tuottaako dokumentin joku käsin notepadilla, erikoistuneella XMLeditorilla, sovelluksella Z (tietämättä että tiedot talletetaan XMLmuodossa) vai tuotetaanko dokumentit aina tietokoneohjelman toimesta - onko dokumentteja tarkoitus myös lukea "sellaisenaan" Esimerkki; täyttäisitkö sinä seuraavan elementin kaikki attribuutit huolella ja ajatuksella aina käsin notepadilla jos elementtejä tulisi kirjoittaa n. 100 per dokumentti: <CHPTER EDITOR="ON" ORG="TUT/DMI" LSTMOD="13.3.2000" KEYWORDS="xml css" LEVEL="very easy" REFBOOKSS="Dragonbook C-bible" TYPE="theory" xml:lang="en" PREREQUISITES="EBNF HTML3.2">... Jos tiedetään, että XML-dokumentteja kirjoittavat ja lukevat ainoastaan tietokoneohjelmat, suunnittelun painopiste siirtyy "käyttömukavuudesta" laajennettavuuteen ja tehokkuuteen Jos tiedetään, että käyttäjät tuottavat dokumentteja etupäässä editorilla BC (tai sellainen aiotaan kirjoittaa/ottaa käyttöön N vuoden päästä), kannattaa tämä ottaa reilusti huomioon mietittäessä, miten ja millä tarkkuudella merkkausta kannattaa kirjoittaa 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 266

Dokumenttiluokan määrittely skeeman määrittäminen Kun tiedetään, minkälaisesta dokumenttiluokasta ja minkä tasoisesta merkkauskäytännöstä (määrittelyvaiheen tarkkuudella) ollaan kiinnostuneita, voidaan suunnitella ja kirjoittaa täsmällinen kuvaus dokumenttiluokan dokumenttien koodauksesta ja loogisesta rakenteesta Viime kädessä kyse on dokumenttiluokan kuvaavan skeeman ([schema]) määrittelystä (vrt. tietokantojen määrittely). Skeemalla tarkoitetaan tässä yhteydessä lähinnä: - täsmällistä mallia ([model]), joka kuvaa dokumenttien koodauksen ja rakenteen J - mallille asetettavia rajoituksia ([constraints]), jotka rajaavat mallin elementtirakennetta ([content constraint]) ja elementtien sisältöä ([datatype constraint]) Skeeman kuvaamiseen on useita vaihtoehtoja: 1) ohjeistus sanallisesti tai esimerkkien kautta (skeeman määrittely viitaten "tunnettuihin tietotyyppeihin", "malliesimerkkeihin", jne.) 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 267

2) dokumenttiluokan kuvaaminen XML DTD:n muodossa (skeeman määrittely XML-merkkausdeklaraatioina) 3) dokumenttiluokan kuvaaminen XML Scheman avulla (skeeman määrittely XML Schema -spesifikaation mukaisina kuvausrakenteina) 4) 5) dokumenttiluokan kuvaaminen täsmällisesti suoraan "matalan tason" työvälineillä (esim. suoraan EBNF-notaatiota käyttäen) Tällä kurssilla keskitytään lähinnä tapojen 1 ja 2 yhteiskäytäntöön (="tavallinen tapaus"). Tapaus 3 käsitellään pintapuolisesti XML-stdperheen yhteydessä Skeemaa suunniteltaessa kannattaa käyttää tervettä kaupunkilaisjärkeä: - täsmällisyyteen ei tarkoita samaa kuin "formaalisen näköiseen" pyrkiminen - formaalisella skeeman määrittelyllä ei ole "itseisarvoa" jos esimerkit ajavat saman asian paremmin (paitsi jos tavoitteena malli ohjelmatoteutukselle) - määrittely kannattaa aluksi tehdä niin yksinkertaisesti kuin mahdollista ja miettiä monipuolisempia rakenteita vasta kun nähdään, kelpaako skeema mihinkään 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 268

Dokumenttiluokkien skeemat Dokumenttiluokkien määrittelyn tapauksessa tyypillisen skeeman malli sisältää seuraavankaltaisia osia: - geneerisen mallin yleiselle elementtihierarkialle - tietue-elementtien esittelyn ja kuvaukset (tietue-elementit samaistetaan tässä kirjallisuudessa mainittavien "informaatioyksiköiden" ja XML Scheman "tyypiltään kompleksisten elementtien" kanssa) - dataelementtien esittelyn ja kuvaukset Tyypillisiä rajoitteita puolestaan ovat: - geneerisen mallin rakennetta säätelevät rajoitteet - dataelementtien sisältämän tiedon tyypin semanttiset rajoitteet - dataelementtien sisältämän tiedon syntaktista rakennetta koskevat rajoitteet 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 269

Esimerkki kirjeiden luokan määrittävästä skeemasta TO LETTER CONTENT? FROM malli korkean tason elementtihierarkiasta {1,7} PERSON CHPTER PERSON PERSON tietue-elementtien mallit LSTNME EMIL LSTNME TYPE: string PTTERN: \u\w\w+\s\u\w\w+ EMIL TYPE: string PTTERN: \w+@[\w\.]+ CHPTER TYPE: string PTTERN:. dataelementtien kuvaus Huomaa eri tasot ja XML:n DTD-määrittelyn ulottumattomissa olevat piirteet! 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 270

Systemaattiset suunnittelumenetelmät Miten hyvään skeemaan sitten päädytään? "Riittävän laaja" kokeileminen ja testaus on varma tapa tuottaa tuloksia mutta suuremmissa suunnittelutöissä se yleensä yksin ole riittävän tehokas tai luotettava Kokeileminenkin on vain osa suunnittelutyötä: kokeilun perusteella ongelmaa analysoidaan, mallinnetaan dokumenttiluokka ja lopuksi toteutetaan se. Koko ajan pidetään kirjaa siitä mitä tuli tehtyä, miksi ja miten Mikäli suunnittelukäytäntö on epäselvä, seurauksena on ikäviä ongelmia: - tekijätiimin huonomuistisuus aiheuttaa virheitä ja tehottomuutta (samaa jauhetaan kerrasta toiseen ja ratkaisut keksitään aina uudelleen) - tavoitteet ja tulokset ovat epäselviä ja muuttuvat huomaamatta matkalla - oikeita kysymyksiä ei huomata kysyä oikeina aikoina tai unohdetaan kokonaisia työvaiheita (tyypillisesti dokumentointi) - suunnitteluprosessin seuraaminen on hankalaa ja tehtyjen päätösten vaikutusten arvioiminen jälkikäteen (ja esim. työstä oppiminen!) vaikeaa 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 271

Ratkaisuja ongelmiin pyrkivät tarjoamaan erilaiset systemaattiset suunnittelumenetelmät, jotka olennaisesti tiivistävät ja yleistävät aikaisemmista suunnittelu- ja toteutustöistä saatuja kokemuksia (ja Gurujen näkemyksiä) Suunnittelumenetelmien voiman perustana on yleensä kuvaustekniikoita ja menetelmiä: - yhtenäinen kieli ja käsitejärjestelmä jonka avulla esittää suunnitelmia ja keskustella niistä - selkeä malli suunnitteluprosessin toteuttamiseksi J kirjaamiseksi - muistilistoja joiden seuraaminen varmistaa pahimpien sudenkuoppien välttämisen työn eri vaiheissa - esimerkkejä joista ottaa mallia työn suorittamiseksi käytännössä Olemassa olevien suunnittelumenetelmien (tai yleisten systeemityön menetelmien) hyödyntämiseen on kärjistetysti kaksi vaihtoehtoa: 1) opiskellaan menetelmä Ö (esim. OMT, UML, jokin ISO- tai IEEE-standardi tai opiskellaan jokin kirjaklassikko) läpikotaisin ja sovelletaan sitä TI 2) mietitään mikä menetelmien käytössä on oleellista ja valitaan eri menetelmistä hyviä puolia ja sovelletaan niitä omassa työssä 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 272

Menetelmät voidaan jakaa eri luokkiin mv. arviointikriteerien perusteella. Tavallinen jako perustuu menetelmän muodollisuuteen. Tällöin luokat ovat: a) vapaamuotoiset (informaalit) menetelmät b) puoliformaalit menetelmät c) formaalit menetelmät Luokittelu on tuttu ohjelmistosuunnittelusta (vrt. esim. seinätaulut/omt/vdm) Dokumenttiluokkien määrittelyssä tyypillinen lähestymistapa ovat puoliformaalit menetelmät: - esitutkimus ja määrittely suoritetaan luonnollisen kielen avulla - suunnitteluprosessi organisoidaan käytännöllisten menetelmien avulla - suunnitteluprosessin osina käytettävät kuvausmenetelmät sisältävät formaalisia osia Tämän kurssin "menetelmätason" lähestymistapa noudattelee tapausta 2b seuraavasti: - kootaan karkea muistilista dokumenttiluokan loogisen rakenteen analysoinnin ja suunnittelun eri vaiheista ja kriittisistä tehtävistä 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 273

- esitellään yksinkertaisia visuaalisia menetelmiä ("kuvaustekniikoita") jotka helpottavat elementtirakenteista puhumista - kuvaustekniikoiden tarkkuus (formaalisuuden aste) voidaan valita sopivaksi suunnitteluvaiheessa On syytä huomata, että dokumenttiluokan toteuttaminen on tyypillisesti (esim. ohjelmistotyön) osaprojekti, mistä tietenkin seuraa omia rajoitteitaan Koostetaan jatkossa asian edetessä esimerkinomaisesti lyhyttä muistilistaa suunnittelu- ja toteutusvaiheen tehtävistä (lähdettä Maler et al, 1996 mukaillen). Kun alustavat kokeilut on tehty ja aineistoa saatavilla, on vuorossa: Vaihe 1: elementtien tunnistaminen - Tunnista ja määrittele tarkasti kaikki mahdolliset semanttiset komponentit (sisältö- ja rakennetyyppiset elementit) - Merkitse muistiin esimerkkitapaukset joiden perusteella elementtiä saatettaisiin tarvita - Epäselvissä tapauksissa ota mukaan suunnitteluun enemmän elementtejä kuin tarpeen ja karsi elementtejä suunnittelun myöhäisemmässä vaiheessa 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 274

Tärkeä syrjähyppy: suunnittelun visuaaliset apuvälineet Yksinkertaisen XML-dokumenttiluokan suunnittelu ja kirjoittaminen onnistuu yleensä hyvin suoraan merkkausdeklaraationa eikä välttämättä vaadi tuekseen erityisiä visualisointimenetelmiä Merkkausdeklaraation kirjoittaminen suoraan määrittelyvaiheen pohjalta ei kuitenkaan aina ole perusteltua: - kuvien perusteella keskusteleminen on usein tekstiesitystä helpompaa (havainnollisempaa ja nopeampaa) - merkkausdeklaraatioiden lukeminen ja elementtirakenteiden hahmottaminen saattaa olla "ei-teknisille" henkilöille hankalaa (tällöin kynnys rakentavan keskustelun aloittamiselle on tarpeettoman korkea) - suunnittelutyössä rajoittuminen XML-merkkausdeklaraatioihin ei aina ole tarkoituksenmukaista vaikka XML DTD:tä aiottaisiinkin varmasti käyttää dokumenttiluokan määrittelyssä (merkkausdeklaraation tarkka syntaksi saattaa sovelluksen näkökulmasta olla rajoittunutta ja kömpelöä) - visuaalisten menetelmien ilmaisuvoimaa voidaan tarvittaessa "helposti" lisätä sopimalla uusia merkintöjä 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 275

Dokumenttiluokan visualisoimiseen on kärjistäen kaksi eri lähtökohtaa: 1) visualisoiminen kieliopin rakenteen kautta tai 2) visualisoiminen dokumenttien jäsennyspuiden kautta Esimerkki: olkoon dokumenttiluokka muotoa <!DOCTYPE DOC <!DOCTYPE CONTENT <!DOCTYPE TITLE <!DOCTYPE HEDING <!DOCTYPE PR <!DOCTYPE UTHOR (TITLE,CONTENT,UTHOR)> (HEDING,PR)+> (#PCDT)> (#PCDT)> (#PCDT)> (#PCDT)> Nyt elementtirakenteen esittävän kieliopin tuottosäännöt ilmeisestikin voidaan esittää sopivasti valitun automaatin avulla loogisen elementtirakenteen tarkkuudella esim. seuraavasti: DOC: TITLE CONTENT UTHOR CONTENT: HEDING PR 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 276

Vastaavasti kaikki kieliopin mukaiset dokumentit voidaan esittää esim. jo tutuksi käyneessä puumuodossa: DOC TITLE #PCDT CONTENT + UTHOR #PCDT HEDING PR #PCDT #PCDT Visualisointitavoille on omat nimensäkin: rakennediagrammi ([structure diagram]) ja ELM-puudiagrammi ([elm tree diagram] lyhenne ELM tulee sanoista Enables Lucid Models) Huomaa miten samat perusideat (graafit, formaalisten kielten ideat, nimeämiskäytännöt) toistuvat eri kuvausmenetelmissä (kuten eri menetelmissä ja formalismeissa ylipäänsä) 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 277

Puiden käyttö dokumenttirakenteiden visualisoinnissa (erityisesti heterogeenisen taustan omaavien tekijätiimien kesken) on käytännössä todettu automaatteja helpommaksi, vaikka 1:1-vastaavuuteen asiasisällön kanssa molemmilla lähestymistavoilla onkin (ilmeisesti) helppo päästä utomaattien käyttämisestä saattaa kuitenkin olla apua esim. merkkausdeklaraatioita suunniteltaessa Suunnittelun visuaalisten apuvälineiden, erityisesti puudiagrammien käyttöä puoltaa erityisesti se seikka, että kuvallisten rakenteiden hahmottaminen "yhdellä silmäyksellä" on mahdollista, kun taas tekstimuodossa annetut rakenteet pitää pääsääntöisesti "lukea ensin ymmärtämistä" Tässä vaiheessa on syytä vielä huomauttaa, että vaikka esitetty puukaavioiden piirtotapa noudattaakin suuresti XML DTD-määrittelyä, niin kyse on silti pikemminkin dokumentin loogisen rakenteen suunnittelusta kuin DTDsuunnittelusta - sama looginen dokumenttirakenne kun voidaan määritellä useilla eri tavoilla (joista vain yksi tapa on XML DTD-formalismi) Edelleen on syytä huomata, että perus-xml tarjoaa varsin niukasti mahdollisuuksia skeemojen rajoitteiden asettamiseen, vaan nämä on joko esitettävä muita standardeja (mahdollisesti XML-standardiperheen standardeja) käyttäen tai sitten toteutettava XML-prosessorin lisäosana 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 278

Rakennediagrammit dokumenttien visualisoinnin välineinä Rakennediagrammien (oleellisesti automaattien) käyttö soveltuu lähinnä annetun kieliopin toiminnan hahmottamiseen Idea perustuu automaattien luonteenomaiseen toimintaan: sopivasti konstruoitu äärellinen (epädeterministinen) automaatti voi paitsi tunnistaa kielen, myös ikuisesti toimiessaan luetella kaikki kielen sanat (ei kuitenkaan minkä tahansa kielen!) Yksinkertaisen automaatin toimintaperiaate on intuitiivinen: äärellinen automaatti joko generoi tai tunnistaa (sopivan säännöllisen kielen) sanat Esimerkki 1: utomaatti G tuottaa kielen (B+ C)DE[FG] sanat G: B F D E C G 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 279

Esimerkki 2: utomaatti R tunnistaa kielen (B+ C)DE[FG] sanat R: B B D E F C G Esimerkkejä kielen sanoista: L(G) = {, CDEG, BDEF, BBBBBBBBBBBBBBDEG, } Peruskäsitteitä: - alkutila - lopputila - tilasiirtymä - λ-siirtymät - epädeterministisyys 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 280

Huomioita: - automaatit ovat "algoritmien rakennuspalikoita" - yhden ja saman asian voi toteuttaa eri automaateilla - äärellisillä automaateilla voi tuottaa ja tunnistaa VIN säännöllisiä kieliä - säännöllisiä kieliä voidaan esittää myös säännöllisten lausekkeiden avulla (huomaa eri merkkauskäytännöt) Koska vastaavuus kielioppien kanssa on ilmeinen, annetaan rakennediagrammien syntaksi ja semantiikka XML-elementtimallien avulla: () ( B) B (,B) B Tulkinta on selvä: lähdetään liikkeelle nuolen alusta ja kuljetaan jotakin kulkua pitkin automaatin läpi vasemmalta oikealle: dokumenttiin valitaan ne elementit, joita vastaavien automaatin tilojen läpi kuljettiin 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 281

Kertojien avulla voidaan XML-dokumentteihin tuottaa äärettömiä elementtirakenteita. Rakennediagrammeissa kertojia vastaavat silmukat: (+) (*) (?) Loput rakennediagrammit saadaan edellisiä yhdistelemällä Käyttöön voidaan ottaa muitakin kertojia ja säännöllisistä lausekkeista tuttuja sievennysmerkintöjä (näitä esitellään lisää jäljempänä). Edellisten lisäksi voidaan ottaa käyttöön sievennysmerkintänä vielä esimerkiksi operaattori &: B "&B" ~ ((,B) (B,)) B 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 282

Rakennediagrammeja voi luontevasti myös automaattien tavoin jakaa osiin: BODY HTML: HED FRMESET HED: TITLE MET Näkyviin voidaan vielä erikseen merkitä tieto siitä, mitkä tilat vastaavat terminaalielementtejä (esim. yo. kuvassa kolmio elementeissä TITLE ja MET) Diagrammien havainnollisuus riippuu kohderyhmästä: sen sijaan, että käyttäisi rakennediagrammeja jatkuvasti suunnittelun apuna, voi olla hyödyllisempää käyttää niitä vain tekijätiimin koulutusvaiheessa: diagrammien avulla on helppo selittää mitä elementtimallit "tarkoittavat" "mmattilaiskäytössä" selkeä ja kauniisti sisennetty merkkausdeklaraatio ajaa kuitenkin yleensä saman asian 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 283

Puudiagrammit dokumenttien visualisoinnin välineinä Puudiagrammien käyttö suunnittelun tukena on intuitiivista ja oman puudiagrammikielen keksiminen on helppoa. Käyttöön on kuitenkin vakiintunut jo oma merkintätapansa, jonka muistaminen helpottaa keskustelua Perusidea on dokumentin rakenteen piirtäminen sen loogisen elementtirakenteen jäsennyspuun avulla mahdollisimman "laajassa" muodossa, ts. tavoittaen yhdellä kuvalla koko dokumenttiluokan dokumenttien geneerisen rakenteen (joka "yleensä" on ääretön) Käytännössä tämä onnistuu kun äärettömät tai optionaaliset rakenteet kirjoitetaan kertojien avulla lyhennetyssä muodossa Pääpaino on elementtirakenteiden visualisoimisessa: attribuutit merkitään näkyviin "tarvittaessa" ja muu merkkaus, esim. kommentit ja prosessointiohjeet jätetään yleensä kokonaan pois Seuraavissa esimerkeissä elm-puudiagrammeja vastaavia dokumenttiluokkia esitetään XML- dokumenttien ja XML DTD-määritysten avulla, ts. (joillekin) puudiagrammeille annetaan tulkita XML-spesifikaation kautta 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 284

On erittäin tärkeää huomata, että - puudiagrammit eivät sinänsä "tarvitse" DTD-määrityksiä tuekseen, vaan niiden semantiikka voidaan ymmärtää intuitiivisesti esim. dokumenttiesimerkkien kautta - puudiagrammien avulla voidaan yleispätevästi kuvata myös muita (dokumentti)rakenteita kuin mitä XML DTD-määritysten avulla voidaan esittää (dokumenttien merkkaus voi silti noudattaa XML-spesifikaatiota!) - puudiagrammien notaatiota voidaan helposti laajentaa XML DTDmääritystä vahvemmaksi Käsitellään seuraavaksi elm-puudiagrammien syntaksi ja semantiikka kokonaisuudessaan XML-esimerkkien avulla: B C B C <!ELEMENT (B)> <!ELEMENT (B,C)> <!ELEMENT (B C)> 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 285

B C B C <!ELEMENT (B C ) > <!ELEMENT (B,C ) > Yllä puun haaroihin on vielä liitetty kertojia: kertojaksi voidaan tuttuun tapaan valita jokin seuraavista:?,*,+ tai jättää kokonaan merkitsemättä XML- elementin sisältö merkitään jossakin seuraavassa muodossa: #PCDT B * #PCDT <!ELEMENT EMPTY> <!ELEMENT (#PCDT)> <!ELEMENT (#PCDT B)*> 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 286

Muut puudiagrammit saadaan oleellisesti yhdistelemällä edellisiä Huomioita: - yhden ja saman dokumenttiluokan määrittely voidaan suorittaa "erinäköisten" puudiagrammien avulla - jo edellisiä rakenteita yhdistelemällä voidaan esittää loogisia dokumenttiluokkia, joiden määrittely XML DTD-muodossa ei ole mahdollista (näiden merkkaaminen voi kuitenkin onnistua XMLdokumenttien muodossa) Puudiagrammeja voidaan käyttää myös laajemmassa muodossa suunnittelun apuna ottamalla käyttöön lisää merkintöjä: (REF) "TEKSTIÄ" B eclass kuvaus jatkuu toisaalla elementin sisältö kuvataan vapaamuotoisesti (suunnittelu kesken tms.) elementtiluokkaan eclass viitataan entiteetin avulla: <!ELEMENT (B,(%eclass;))> 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 287

Tämäntyyppiset merkinnät lähinnä helpottavat suurten rakenteiden hahmottamista ja helpottavat työn tekemistä käytännössä (suuren puudiagrammin piirtäminen "kerralla oikein" ei yleensä onnistu) Merkintöjä voidaan edelleen sieventää ottamalla käyttöön uusi operaattori & sekä lyhyempi tapa ilmoittaa toistuvia elementtirakenteita kertojien muodossa: nnetaan esimerkkejä näiden käytöstä: {1,3} 3+ B C B C <!ELEMENT (((B (B,B)) (B,B,B)),C,C,C+)> :n malli on B&C ~ <!ELEMENT ((B,C) (C,B))> Edelliset laajennukset eivät taaskaan tuo lisää vahvuutta dokumenttiluokan määrittelyyn, vaan sieventävät olemassa olevia merkintöjä Sievennyskäytäntöjen ideoiden ymmärtäminen helpottaa sekä laajempien standardien (esim. SGML) että toisten ad hoc -diagrammien lukemista 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 288

ttribuutit merkitään näkyviin niiden elementtien yhteyteen, joihin attribuutit liitetään ID=ID VL=CDT? DESC=CDT("ed")? B C COL=(RED GREEN) D IDNME=ID? TBLEREF=IDREF <!ELEMENT (B C)> <!TTLIST ID ID #REQUIRED VL CDT #IMPLIED> <!TTLIST C COL (RED GREEN) "RED"> <!ELEMENT (D?)> <!TTLIST DESC CDT "ed"> <!TTLIST D IDNME ID #IMPLIED TBLEREF IDREF #REQUIRED> ttribuutit voidaan tietenkin merkitä näkyviin myös vapaamuotoisina kuvauksia kertomalla niiden merkitys, esimerkiksi yllä elementin D attribuutti TBLEREF olisi voitu hyvinkin merkitä muodossa "TBLEREF: viittaus taulukkoon" tms. ttribuuttien tavoin elementtien yhteyteen voidaan merkitä myös kommentteja ja huomautuksia: oleellista on notaation systemaattisuus Diagrammeissa ei aina kannatta mennä yksityiskohtiin, vaan kyseessä voi hyvin olla välituotos, josta yksityiskohtaisempi skeema kirjoitetaan myöhemmin 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 289

Esimerkki puudiagrammien käyttämisestä NME TPE SONGS STYLE=(CUSTOM JZZ CLSSLIC POP ROCK)? DBINFO #PCDT + SONG ID=ID LENGTH=NMTOKEN + METDT FOR THE DB MNGER TITLE MUSICIN MUSICIN ID=ID NME #PCDT? DESC #PCDT INSTRUMENT=(VIOLIN PINO FLUTE) GE=NMTOKEN? STYLE=(CUSTOM JZZ CLSSLIC POP ROCK SOUL) SONGS=IDREFS? (LINKS TO DIFFERENT SONGS) Huomaa jako osiin: ylärakenne vs. tietue-elementit ja epämääräiset kohdat 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 290

Elementtien semantiikka - mitä ollaan merkkaamassa? Palataan sitten varsinaiseen aiheeseen eli dokumenttiluokan suunnitteluun ina välillä dokumenttien rakennetta hahmotellessa kannattaa miettiä mihin seuraavista kategorioista ehdotetut elementit kuuluisivat: - sisältö ([content]) - rakenne ([structure]) - esitystapa ([presentation]) Esimerkkejä sisältö-tyyppisistä elementeistä: osoite, katu, koneen osanumero, myyntiartikkelin lukumäärä, hinta, erisnimi, kuvaus, tietokoneohjelman komento, kakkureseptin raakaaine, paistolämpötila Esimerkkejä rakenne-tyyppisistä elementeistä: luku, kappale, lista, luettelo, taulukko, palsta, metodi, luokka, säiliö, joukko, relaatio 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 291

Esimerkkejä esitystapa-tyyppisistä elementeistä: Dokumenttiluokan toteuttamisesta tietyn näköinen elementti, fontilla Y merkitty kappale, kuva, vaakaviiva, sivunvaihdon merkitsevä elementti, varjostus, vakioteksti, logo, sivunumero, kaavion tai kappaleen numero Jos todella halutaan suunnitella rakenteellisia dokumentteja, on jatko selviö: - rakenne-tyyppisiä elementtejä käytetään sisältö-tyyppisten elementtien ryhmittelyyn - esitystapa-tyyppiset elementit pudotetaan kokonaan pois ja otetaan käyttöön myöhemmin tyylimääritysten muodossa (se, että homma todella onnistuu pitää etukäteen tietenkin tutkia, testata ja dokumentoida!) Erityisen suurta huomiota kannattaa kiinnittää: - kuvaavien nimien keksimiseen (sovellusalueen luonnolliset nimet, ei jargonia, "RECORD" parempi kuin "RC", "FILE" parempi kuin "SEQDBOBJECT") - yleiskäyttöisten rakenteiden suunnitteluun (hyvät perusideat toistuvat) - määrittelyn systemaattisuuteen (esim. nimissä ei yhtäällä "File" ja toisaalla "MENU" ellei kirjainkoon erottelulla ole selkeää tulkintaa) 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 292

sillä hyvin mietittyinä nämä helpottavat dokumenttiluokan käyttöönottoa ja vähentävät "turhaa muistamista" Dokumenttirakenteen mallintamista helpottaa jatkossa elementtiehdokkaiden luokittelu ja sijoittelu rakenne-tyyppisten elementtien sisälle Vaihe 2: elementtien luokittelu - Luokittele elementtiehdokkaat alustavasti näiden (rakenteellisten) ominaisuuksien perusteella - Älä pakota luokittelua äläkä kiirehdi tekemään lopullisia valintoja liian varhaisessa vaiheessa suunnittelua Elementtien luokittelun tarkoituksena on käydä systemaattisesti läpi työn alla olevan merkintäkielen ilmaisuvoimaa ([richness]) ja aluetta ([scope]) jakamalla elementit luokkiin niiden käyttötarkoituksen, rakenteen ja keskinäisten suhteiden perusteella Elementtien alustavassa määrittelyssä ja luokittelussa kannattaa varoa: - ensimmäisiin ideoihin takertumista tai pakotettujen teknisten ratkaisujen soveltamista 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 293

- samojen nimien tai rakenteiden käyttöä eri merkityksissä ja nimiavaruuksien sekoittumista jonkin "lähellä olevan" dokumenttiluokan kanssa - rakenteen ja ulkoasun sekoittumista suunnittelussa - hankalien merkkausrakenteiden pakottamista "varmuuden vuoksi, ettei mitään tietoa jäisi pois" Elementtien luokittelu luokkiin "rakenne" ja "sisältö" toimii perustana vaiheiden muistilistan 5-7 suorittamiselle (hierarkia, tietueet ja data) Merkkauksen monimutkaisuus kannattaa pitää terveen järjen rajoissa: merkkauksesta ja metatiedosta on laajamittaisesti hyötyä vain jos - informaatio on luotettavaa, - sitä on riittävästi saatavilla J - merkkaus systemaattista Pieni on kaunista (yksinkertaisuudellakin on toki sovelluskohtaiset mielekkäät rajansa) 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 294

DTD-suunnittelijakaan ei ole saari Hyvä DTD-suunnittelija hallitsee "kenttänsä": tuntee vakioratkaisut ja tietää suunnilleen, mitä lähestymistavasta X seuraa Lähtökohdan "kentän tuntemiselle" tarjoaa tyypillisesti oma sovellusalue: harvoin löytyy sovellusaluetta, jolla joku toinen ei aikaisemmin olisi tehnyt samantyyppistä työtä kuin mitä nyt ollaan tekemässä. Laajoja "tunnettuja" esimerkkejä tarjoavat esim. (lisää löytyy eri yhteisöjen arkistoista) - MS XML Scenarios (ks. http://msdn.microsoft.com/xml/scenario/intro.asp) - Text Encoding Initiative (ks. ftp://ftp-tei.uic.edu/pub/tei/index.html) - DocBook (ks. http://www.oasis-open.org/docbook/index.html) Vaihe 3: esimerkeistä oppiminen - Etsi esimerkkejä muiden tekemistä "samantyyppisistä" analyyseistä ja vertaa näitä omaan työhösi - Älä kuitenkaan sovella toisten esimerkkejä omassa työssäsi ellet ymmärrä heidän tavoitteitaan ja tekemiään suunnitteluvalintoja 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 295

Elementtien valitseminen ja rakenteen jäsentäminen Kun peruselementit (ja attribuutit) on alustavasti valittu, on aika ryhtyä mallintamaan dokumenttiluokkaa Työ alkaa karsimalla ja täsmentämällä alustavasti valittuja elementtejä. Niitä kannattaa nyt vielä kerran yksitellen tutkia seuraavasta näkökulmasta: - toteuttaako elementti todellakin suoraan tai välillisesti tavoitteita joita määrittelyssä asetettiin vai "puhuuko se eri asiasta"? - ovatko elementin tarkkuus ja laajuus sopivia vai onko se esim. liian yleinen ollakseen hyödyllinen? - onko elementille käyttöä muussakin kuin esimerkkiaineistossa vai onko se liian spesifi ollakseen käyttökelpoinen? - lokeroiko elementti todella tietoa vai onko se vain "tulostettavaksi tarkoitettu kenttä"? - löytyykö elementille tässä ja nyt konkreettista käyttöä vai onko se vain jotain joka "saattaa osoittautua hyödylliseksi joskus myöhemmin"? 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 296

Vaihe 4: elementtien valinta - Käy elementtiehdokkaat läpi ja valitse lopulliset kuvailevat elementit - Merkitse muistiin syyt joiden perusteella valinnat suoritettiin - Älä säilytä elementtejä joille et keksi realistista käyttöä Kun elementit ovat (alustavan valinnan mukaisesti) selvillä, on aika jäsentää ne dokumentiksi (tietoisesti varoen "hukkaamasta" informaatiota matkalla) Dokumentin elementtihierarkia alkaa rakenne-elementeistä, jäsentyy toistuviksi tietue-elementeiksi ja päättyy dataelementteihin, "tekstiin" tai "asiasisältöön" Vaihe 5: elementtihierarkian ja metatiedon koostaminen - Tunnista rakenne-elementit ja järjestä ne puurakenteeksi - Muodosta hierarkkinen rakenne niin tarkasti kuin olemassa oleva suunnittelutyö sen järkevästi sallii ja jätä epäselvät lapsisolmut jäsentämättä - Kirjaa taas suunnittelutyö muistiin ja perustele rakenteen valinta Tämän työn alustavana tuloksena on tyypillisesti puudiagrammi, jonka lehtinä esiintyy runsaasti "pilviä" (ts. puu sisältää vielä jäsentymättömiä haaroja) 73275 RKENTEISET DOKUMENTIT (kevät 2002) luentorunko ON 297

Informaation luontaisen hienorakenteen tunnistaminen Perushierarkian koostamisen jälkeen on aika jäsentää dokumenttiluokan mallia Vaihe 6: tietue-elementtien kokoaminen - Tunnista tietue-elementit ("informaatioyksiköt") jäljellä olevista (tyypillisesti vielä jäsentämättömistä) elementtirakenteista - Mallinna näiden sisäinen rakenne sopusoinnussa (vaiheiden 5 ja 7 kanssa) - Merkitse muistiin syyt joiden perusteella valinnat suoritettiin On ilmeistä, että tietue-elementtien nimeäminen on periaatteessa mielivaltaista Käytännössä tietue-elementtien valitseminen on kuitenkin kohtalaisen suoraviivaista, sillä "yleensä" tietue-elementit - mukailevat "luonnollisen" käsitejärjestelmän objekteja ("maailman luonnollinen ontologia"), - toistuvat dokumenteissa, tai - kuvautuvat sovellusalueen "vakiintuneiksi" tietorakenteiksi 73275 RKENTEISET DOKUMENTIT (kevät 2000) 298

Kun tietue-elementit on mallinnettu ja kuvattu, käydään läpi jäljellä olevat elementit ja viimeistellään dokumenttiluokkaa vastaavan puudiagrammin lehdet Vaihe 7: dataelementtien kokoaminen - Käy jäljellä olevat semanttiset elementtiehdokkaat läpi ja identifioi ja valitse joukosta loput dataelementit - Kuvaa dataelementit yksinkertaisten elementti- ja attribuuttirakenteiden kanssa, kuvaa näiden tietomallit yksityiskohtaisesti - Merkitse muistiin syyt joiden perusteella valinnat suoritettiin - Pyri järkevästi minimoimaan dataelementtien määrä: älä ahnehdi useita dataelementtityyppejä, koska tällöin vaarana on dataelementtien epämääräinen käyttäminen tulevaisuudessa - Pyri yksinkertaisuuteen Dataelementtien kokoamisen yhteydessä niitä voidaan vielä muuttaa ja yleistää (tyypillisesti konteksti kertoo tulkinnan) jotta dokumentin koodauskäytäntö saataisiin yhtenäistettyä 73275 RKENTEISET DOKUMENTIT (kevät 2000) 299

Vaihe 7 edellyttää myös jossain määrin tietoa siitä, miten tietoa viime kädessä käsitellään esim. tyylimäärityksen tai yleisen sovelluksen toimesta Huomiota voidaan kiinnittää myös esim. - metatietoon: varmistamalla merkkaus riittävän ilmaisuvoimaiseksi sovellusta Y silmälläpitäen (lisäten metatietoa tarvittaessa) - sieventämiseen: toistuvien (ja muuttuvien) vakio- ja fraasirakenteiden tunnistaminen (ja koodaaminen esim. entiteettien avulla) - automatisoitavuuteen: varmistamalla automatisoitujen toimintojen toteuttamiskelpoisuus jatkossa (esim. automaattinen indeksointi, linkitys tai hakemisto) Tässä vaiheessa työn tuloksena voi esimerkiksi olla jotakin kuvan sivulla 260 kaltaista: - iso hierarkkinen yleisrakenne (kätevä esittää puudiagrammina) - pieniä tietue-elementtejä kuvaavia malleja (puudiagrammit sopivat tähänkin hommaan) Nyt viimeistään joudutaan ottamaan kantaa myös kysymykseen skeeman määrittelyyn käytettävästä formalismista (jos hommaa halutaan automatisoida) 73275 RKENTEISET DOKUMENTIT (kevät 2000) 300

Hienorakenteen ja hierarkian yhdistäminen, linkitys Kun dokumenttiluokan dokumenttien perushierarkia on valittu ja tietueelementit valittu, pitää eritasoiset näkymät informaatioon yhdistää - muutenhan osamallit eivät muodosta yhtenäistä kokonaisuutta Vaihe 8: eritasoisten rakennemallien yhdistäminen - Käy tietue-elementit ja dataelementit jokaisen "miehittämättömän" puudiagrammin osalta läpi ja kirjaa missä kohdissa ko. elementtien tulisi esiintyä (ts. käy läpi kaikki näiden mahdolliset kontekstit) - Tunnista ja nimeä kaikki esiintymiskohdat ja etsi elementtien esiintymistavoista säännönmukaisuuksia - Mallinna säännönmukaisuudet sopivista tietue- ja dataelementeistä koostuvilla elementtimalleilla. Liitä ko. mallit kontekstielementteihin (saattaa edellyttää säiliöelementtien lisäämistä) - Pyri nimeämään kontekstit mahdollisimman kuvaavasti ja yritä käyttää laajoja elementtimalleja tai elementtiluokkia lukuisten erikoistapausten sijaan 73275 RKENTEISET DOKUMENTIT (kevät 2000) 301

Huomaa, että vasta rakennemallien yhdistäminen tuottaa ensimmäisen yhtenäisen mallin koko dokumenttiluokalle Seuraavaksi on vielä vuorossa sisäinen linkitys ja mallin liittäminen "ulkopuoliseen maailmaan" Linkityksen ideana on merkitä eksplisiittisesti näkyviin hyödyllisiä mutta (toistaiseksi) loogisesta rakenteesta puuttuvia relaatioita ja viittauksia. Tyypillinen dokumenttiluokka sisältää kahdentyyppisiä viittauksia: 1) tietoa siitä miten dokumentteja voidaan "lukea" hypertekstimäisenä (relaatioita tai assosiatiivisia rakenteita) 2) tietoa siitä miten (osa)dokumentteja voidaan tarvittaessa koostaa osista "siellä täällä" sijaitsevista elementeistä (relaatioita) Tapaus 1 liittyy lähinnä jo HTML:stä tuttuun hypertekstin lukuprosessiin - linkit tarjoavat lukijalle keinon navigoida eri dokumenttien väliillä (missä "lukija" voi olla myös tietokoneohjelma) Tapaus 2 liittyy lähinnä (esim. esitettäväksi tarkoitettujen) dokumenttien kokoamiseen (yhden tai useammin dokumentin) osista. siaan palataan XLink ja XSLT-spesifikaatioiden käsittelyn yhteydessä myöhemmin 73275 RKENTEISET DOKUMENTIT (kevät 2000) 302

Liitoskohtien miettiminen edellyttää tietenkin taas tietoa sovelluksen käyttötarkoituksesta ja todennäköisesti jopa tietoa XML-sovellusohjelman toiminnasta (esim. missä muodossa linkkiviittaukset tulee antaa ja miten toisten dokumenttiluokkien elementtirakenteisiin osataan viitata) Vaihe 9: viittauksien luominen - Tunnista kaikki linkkikomponentit (elementit jotka voivat toimia linkkeinä). Kuvaa mitä linkit tarkoittavat, miten ne merkitään, kuinka linkkien seuraaminen tapahtuu, mihin linkit johtavat ja mitä linkin valitsemisesta seuraa - Luokittele linkit näiden toiminnan tai roolien perusteella - Luetteloi kaikki yleiskäyttöiset merkkijonot ja erikoismerkit, joita tekniset kirjoittajat tulevat tarvitsemaan Työ kannattaa pyrkiä kuvaamaan mahdollisimman tyhjentävästi. Älä esim. hiljaisesti oleta linkeille jotain tiettyä oletussemantiikkaa: kirjoita kaikki auki Huomioitavaa: - muista miettiä onko kyseessä yksi-, kaksi vai useammansuuntainen linkki ja varmistaa että linkistä "palaaminen" tarvittaessa onnistuu (jos niin halutaan) 73275 RKENTEISET DOKUMENTIT (kevät 2000) 303

- tuotetaanko linkit käsin vai olisiko työ mahdollista automatisoida esim. sopivan metatiedon avulla - huomioi rajoitteet: ankkureiden nimeämiskäytännöt, nimiavaruudet, saatavuusongelmat, jne. Linkkiviittauksia ei vielä kurssilla ole käsitelty, joten edellä kuvattuun kannattaa palata myöhemmin. Todetaan kuitenkin, että viittaukset voidaan XMLdokumenteissa toteuttaa esim. 1) oman (sovelluksen) mv. tekniikan mukaan 2) ID/IDREF-tekniikalla attribuuttien avulla 3) ulkoisten entiteettien ja (ENTITY-)attribuuttien avulla 4) linkkielementtien avulla käyttäen XML Linking Language (XLink) - spesifikaatiota (käsitellään lyhyesti XML-standardiperheen yhteydessä myöhemmin) Todetaan jo tässä vaiheessa, että XLink tarjoaa mahdollisuuden viitata "mihin tahansa elementtiin mistä tahansa elementistä" (oleellisesti ko. elementteihin liitettävien erityisten XLink-attribuuttien avulla). Myös linkkien semantiikka voidaan valita HTML-linkkejä monipuolisemmin 73275 RKENTEISET DOKUMENTIT (kevät 2000) 304

Työn viimeistely, täsmentäminen ja ylläpito Kun suunnittelu- ja toteutuspuoli on lopulta tehty, on aika (viimeistään) tutkia mitä tuli tehtyä ja ennen kaikkea varmistaa, että: 1) työ tehtiin oikein J 2) tehtiin oikea työ Vaihe 10: työn tulosten varmentaminen ja arviointi - Varmista tuotettujen dokumenttien ja määritysten oikeellisuus ja ristiriidattomuus. Korjaa havaitut puutteet ja epämääräisyydet - Varmista, että kaikki tuotettu aineisto on dokumentoitu ja tallessa - Esittele työsi "asiakkaille" ja käy suunnittelemasi skeema heidän kanssaan yhdessä läpi. Huomioi pidempiaikaiset kokeilut ja selkeä palautteen kerääminen (osa palautteesta jää saamatta jos sen antaminen ei ole helppoa) - Toteuta ehdotetut asialliset korjaukset ja muutokset 73275 RKENTEISET DOKUMENTIT (kevät 2000) 305

Kannattaa todellakin pyrkiä varmistamaan, että työhön oikeasti perehdytään riittävän ajoissa - muutosehdotusten ja toiveiden huomioiminen muuttuu sitä vaikeammaksi mitä myöhemmin ne saadaan (anna asiakkaille esim. kattava arviointilomake - jossa on oltava tilaa myös vapaamuotoisille kommenteille - tms., jotta saat todellista palautetta) Työn arviointivaiheessa löytyy viimeistään käyttöä myös sille dokumentaatiolle, josta suunnitteluvalinnat selviävät (valmis spesifikaatio vastaa yleensä "miksi"- kysymyksiin huomattavasti huonommin kuin "miten"-kysymyksiin) Dokumenttiluokan toteuttamisen ja tulosten varmentamisen jälkeenkään työ ei vielä ole lopussa. Luvassa on vielä ylläpitoa, koulutusta ja kehitystyötä. Ylläpito sisältää tyypillisesti: - käyttökokemusten ja parannusehdotusten ker(j)äämistä - virheiden korjaustyötä, versiointia ja työn dokumentointia - pienten yhteensopivien muutostöiden tekemistä ja dokumentointia - suurten muutostöiden suunnittelua, toteuttamista ja dokumentointia - olemassa olevan dokumentaation päivittämistä muutoksia vastaavaksi 73275 RKENTEISET DOKUMENTIT (kevät 2000) 306

Tehtävät on tietenkin hoidettava yhteistyössä "asioista päättävien tahojen" kanssa - esim. yhteensopiviakaan muutostöitä (esim. pakotetun rakenteen lievennyksiä) ei saa mennä tekemään ilman "virallista hyväksyntää", sillä toteutus ei saa olla ristiriidassa vallitsevan spesifikaation kanssa Todetaan lopuksi vielä kerran, että tietenkään suunnittelumenetelmän (varsinkaan edellä esitetyn lyhyen muistilistan) seuraaminen ei yksin takaa työn onnistumista: paras tapa "varmistaa" dokumenttiluokan toteutustyön onnistuminen on tehdä se mmattitaidolla, jatuksella ja Huolella ("H"), yhteistyössä sisällön asiantuntijoiden ja teknisten kirjoittajien kanssa Muista suunnittelijan mantra (sijoita X:n paikalle sana "skeemoja"): Hyviä X oppii tekemään vain TUNTEMLL SISÄLLÖN, MENETELMÄT J HRJOITTELEMLL KOVSTI Tikulla silmään sitä joka muuta väittää Edellä siis lähinnä esiteltiin työvaiheita, joita dokumenttiluokan "toteuttamiseen" liittyy. Kuitenkaan esim. sitä, millaisia "hyvät" elementtirakenteet sitten ovat, ei yksityiskohtaisesti käsitelty. Yleisessä tapauksessa tämän ohjeistaminen onkin vaikeaa tai jopa mahdotonta. Käydään seuraavaksi läpi rakenteellisten dokumenttien merkitsemiseen liittyviä yksinkertaisia perusvalintoja 73275 RKENTEISET DOKUMENTIT (kevät 2000) 307