Systemaattiset suunnittelumenetelmät

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 ei yleensä yksin ole riittävän tehokas tai luotettava menetelmä 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 265

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 JA 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ä TAI 2) mietitään mikä menetelmien käytössä on oleellista ja valitaan eri menetelmistä hyviä puolia ja sovelletaan niitä omassa työssä 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 266

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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 267

- 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 268

Tärkeä syrjähyppy: suunnittelun visuaaliset apuvälineet Yksinkertaisen XML-dokumenttiluokan suunnittelu ja kirjoittaminen onnistuu yleensä hyvin suoraan merkkausjulistuksina eikä välttämättä vaadi tuekseen erityisiä visualisointimenetelmiä Merkkausjulistusten kirjoittaminen suoraan määrittelyvaiheen pohjalta ei kuitenkaan aina ole perusteltua: - kuvien perusteella keskusteleminen on usein tekstiesitystä helpompaa (havainnollisempaa ja nopeampaa) - merkkausjulistusten 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-merkkausjulistuksiin ei aina ole tarkoituksenmukaista vaikka XML DTD:tä aiottaisiinkin varmasti käyttää dokumenttiluokan määrittelyssä (merkkausjulistuksen tarkka syntaksi saattaa sovelluksen näkökulmasta olla rajoittunutta ja kömpelöä) - visuaalisten menetelmien ilmaisuvoimaa voidaan tarvittaessa lisätä sopimalla uusia merkintöjä 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 269

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 (TITLE,CONTENT,AUTHOR)> <!DOCTYPE CONTENT (HEADING,PARA)+> <!DOCTYPE TITLE (#PCDATA)> <!DOCTYPE HEADING (#PCDATA)> <!DOCTYPE PARA (#PCDATA)> <!DOCTYPE AUTHOR (#PCDATA)> Nyt elementtirakenteen esittävän kieliopin tuottosäännöt ilmeisestikin voidaan esittää sopivasti valitun automaatin avulla loogisen elementtirakenteen tarkkuudella esim. seuraavasti: DOC: TITLE CONTENT AUTHOR CONTENT: HEADING PARA 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 270

Vastaavasti kaikki kieliopin mukaiset dokumentit voidaan esittää esim. jo tutuksi käyneessä puumuodossa: DOC TITLE #PCDATA CONTENT + AUTHOR #PCDATA HEADING PARA #PCDATA #PCDATA 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 271

Puiden käyttö dokumenttirakenteiden visualisoinnissa (erityisesti yhtenäisen 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ä Automaattien käyttämisestä saattaa kuitenkin olla apua esim. merkkausjulistuksia 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 kokonaan ennen 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, joten nämä on joko esitettävä muita standardeja (mahdollisesti XML-standardiperheen standardeja) käyttäen tai sitten toteutettava XML-prosessorin lisäosana 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 272

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: Automaatti G tuottaa kielen A(B+ C)DE[FG] sanat G: B F A D E C G 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 273

Esimerkki 2: Automaatti R tunnistaa kielen A(B+ C)DE[FG] sanat R: B A B D E F C G Esimerkkejä kielen sanoista: L(G) = {, ACDEG, ABDEF, ABBBBBBBBBBBBBBDEG, } Peruskäsitteitä: - alkutila - lopputila - tilasiirtymä - -siirtymät - epädeterministisyys 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 274

Huomioita: - automaatit ovat algoritmien rakennuspalikoita - yhden ja saman asian voi toteuttaa eri automaateilla - äärellisillä automaateilla voi tuottaa ja tunnistaa VAIN 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: A (A) A (A B) A B (A,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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 275

Kertojien avulla voidaan XML-dokumentteihin tuottaa äärettömiä elementtirakenteita. Rakennediagrammeissa kertojia vastaavat silmukat: A (A+) A (A*) A (A?) 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 &: A B "A&B" ~ ((A,B) (B,A)) B A 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 276

Rakennediagrammeja voi luontevasti myös automaattien tavoin jakaa osiin: BODY HTML: HEAD FRAMESET HEAD: TITLE META Näkyviin voidaan vielä erikseen merkitä tieto siitä, mitkä tilat vastaavat terminaalielementtejä (esim. yo. kuvassa kolmio elementeissä TITLE ja META) 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 Asiantuntevassa tekijätiimissä selkeä ja kauniisti sisennetty merkkausjulistus ajaa kuitenkin yleensä saman asian 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 277

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 tulkinta XML-spesifikaation kautta 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 278

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: A A A A B C B C <!ELEMENT A (B)> <!ELEMENT A (B,C)> <!ELEMENT A (B C)> 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 279

A A B C B C <!ELEMENT A (B C ) > <!ELEMENT A (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: A A A #PCDATA B * #PCDATA <!ELEMENT A EMPTY> <!ELEMENT A (#PCDATA)> <!ELEMENT A (#PCDATA B)*> 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 280

Muut puudiagrammit saadaan oleellisesti yhdistelemällä edellisiä Huomioita: - yhden ja saman dokumenttiluokan määrittely voidaan suorittaa useiden erilaisten 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ä: A A A (REF) "TEKSTIÄ" B eclass kuvaus jatkuu toisaalla elementin sisältö kuvataan vapaamuotoisesti (suunnittelu kesken tms.) elementtiluokkaan eclass viitataan entiteetin avulla: <!ELEMENT A (B,(%eclass;))> 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 281

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: Annetaan esimerkkejä näiden käytöstä: A A {1,3} 3+ B C B C <!ELEMENT A (((B (B,B)) (B,B,B)),C,C,C+)> A:n malli on B&C ~ <!ELEMENT A ((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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 282

Attribuutit merkitään näkyviin niiden elementtien yhteyteen, joihin attribuutit liitetään A ID=ID VAL=CDATA? A DESC=CDATA("ed")? B C COL=(RED GREEN) D IDNAME=ID? TABLEREF=IDREF <!ELEMENT A (B C)> <!ATTLIST A ID ID #REQUIRED VAL CDATA #IMPLIED> <!ATTLIST C COL (RED GREEN) "RED"> <!ELEMENT A (D?)> <!ATTLIST A DESC CDATA "ed"> <!ATTLIST D IDNAME ID #IMPLIED TABLEREF IDREF #REQUIRED> Attribuutit voidaan tietenkin merkitä näkyviin myös vapaamuotoisina kuvauksia kertomalla niiden merkitys, esimerkiksi yllä elementin D attribuutti TABLEREF olisi voitu hyvinkin merkitä muodossa "TABLEREF: viittaus taulukkoon" tms. Attribuuttien 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 283

Esimerkki puudiagrammien käyttämisestä NAME TAPE SONGS STYLE=(CUSTOM JAZZ CLASSLIC POP ROCK)? DBINFO #PCDATA + SONG ID=ID LENGTH=NMTOKEN + METADATA FOR THE DB MANAGER TITLE ARTIST ARTIST ID=ID NAME #PCDATA? DESC #PCDATA INSTRUMENT=(VIOLIN PIANO FLUTE) AGE=NMTOKEN? STYLE=(CUSTOM JAZZ CLASSLIC POP ROCK SOUL) SONGS=IDREFS? (LINKS TO DIFFERENT SONGS) Huomaa jako osiin: ylärakenne vs. tietue-elementit ja epämääräiset kohdat 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 284

Elementtien semantiikka - mitä ollaan merkkaamassa? Palataan sitten varsinaiseen aiheeseen eli dokumenttiluokan suunnitteluun Aina 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 285

Esimerkkejä esitystapa-tyyppisistä elementeistä: Dokumenttiluokan toteuttamisesta tietyn näköinen elementti, kirjasimella 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 286

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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 287

- 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 rakenne- ja sisältötyyppisiin 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 JA - merkkaus systemaattista Pieni on kaunista (yksinkertaisuudellakin on toki sovelluskohtaiset mielekkäät rajansa) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 288

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) - Text Encoding Initiative (ks. http://www.tei-c.org/) - DocBook (ks. http://www.oasis-open.org/docbook/) 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 289

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 onko se epäoleellinen? - 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 290

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-symboleja (ts. puu sisältää keskeneräisiä haaroja) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 291

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 - vastaavat sovellusalueen vakiintuneita tietorakenteita 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 292

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 yksilöi 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 293

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 264 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 työtä halutaan automatisoida) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 294

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 keskeneräisen 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 295

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ä erikseen 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 hajallaan sijaitsevista elementeistä (relaatioita) Tapaus 1 liittyy lähinnä jo HTML:stä tuttuun hypertekstin lukuprosessiin - linkit tarjoavat lukijalle keinon navigoida eri dokumenttien välillä (missä lukija voi olla myös tietokoneohjelma) Tapaus 2 liittyy lähinnä (esim. esitettäväksi tarkoitettujen) dokumenttien kokoamiseen (yhden tai useammin dokumentin) osista. Asiaan palataan XLink ja XSLT-spesifikaatioiden käsittelyn yhteydessä myöhemmin 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 296

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 onnistuu tarvittaessa (jos niin halutaan) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 297

- 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 298

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 JA 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 tilaajalle 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 299

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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 300

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 kaikkien osapuolten 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 Ammattitaidolla, Ajatuksella ja Huolella ("AAH"), 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 TUNTEMALLA SISÄLLÖN, MENETELMÄT JA HARJOITTELEMALLA KOVASTI 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 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 301

Merkkauksen valinnan suunnittelufilosofisia päälinjoja Suunnitteluvaiheessa tehty merkkauskäytännön valinta määrää sen, millaista dokumenttien merkkaus tulee olemaan. Sopimaton merkkauskäytäntö hankaloittaa asioita suotta Kannattaa huomata, että sisältö on tärkein ja rakenne tulee vasta toisella sijalla. Sisällöllisesti samanlaisiin dokumenttiluokkiin voidaan yleensä päästä erilaisten rakenteellisten valintojen kautta, joista toiset tyypillisesti ovat parempia kuin toiset Rakenteiden suhteen joudutaan yleensä suorittamaan perusvalinta merkkauksen sisältöspesifisyyden tai pelkän rakenteellisen yhtäläisyyden välillä (esimerkkejä seuraa lisää tuonnempana): - runkona sisällön mukaan nimetyt elementit ([content-based model]) - runkona rakenteen mukaan nimetyt elementit ([structure-based model]) Esimerkki: sisältöspesifisyys vs. geneerisyys <!ELEMENT BOOK (ABSRACT,INTRODUCTION,TERMS,THEORY,MODEL, APPLICATION,REFINEMENT,RESULTS,DISCUSSION,REFS)> <!ELEMENT BOOK (ABSTRACT,SECTION+,REFS)> 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 302

Suunnittelukriteerinä voidaan pitää myös annetun rakenteen jäykkyyttä tai joustavuutta: - (lähes) kaikkien elementtien kirjoittaminen pakollista ([rigid model]) - pakollinen elementtijoukko on pieni ([flexible model]) Esimerkki: jäykkyys vs. joustavuus <!ELEMENT BOOK (ABSRACT,INTRODUCTION,TERMS,THEORY,MODEL, APPLICATION,REFINEMENT,RESULTS,DISCUSSION,REFS)> vs. <!ELEMENT BOOK (ABSRACT,INTRODUCTION?,TERMS?, (THEORY EXAMPLES),MODEL,APPLICATION*, REFINEMENT*,RESULTS,DISCUSSION?,REFS?)> ja jos vapauksia annetaan, kannattaa varmistaa että materiaalintuottajat ja tekniset kirjoittajat eivät mene siitä mistä aita on matalin (terve skeptisyys on kirjoittajien ahkeruuden ja motivoituneisuuden arvioinnissa(kin) paikallaan) Kannattaa kuitenkin muistaa, että rakenteiden jäykkyys voi olla suoraa seurausta suunnittelutyön rajoitteista jotta esim. yhteensopivuus olemassa olevan dokumenttiluokan kanssa voitaisiin varmistetaan (ns. [legacy data]) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 303

Tyypillinen tilanne, jossa jäykkyyden ja joustavuuden välille vedetään selkeä raja on päätös mixed/children element content -tyyppisten elementtien mallien välillä Esimerkki: tekstiä ja elementtejä sekaisin vs. mallinnettu elementtirakenne <!ELEMENT PARAG (#PCDATA EM NOTE QUOTE)*> vs. <!ELEMENT PARAG ((EM? (QUOTE,NOTE)?),TEXT)*> <!ELEMENT TEXT (#PCDATA)> Valinta joudutaan tekemään myös metatiedon eksplisiittisen esittämisen ja kokoamisen suhteen: - kerätäänkö metatietoa valmiiksi omiksi elementeikseen ([metadata approach]) - vai koostetaanko metatieto sieltä täältä dokumenttia vasta tarvittaessa ([inline content approach]) Monipuolisen metatiedon kasaaminen tarvittaessa saattaa joidenkin prosessorien tai editorien yhteydessä olla tietenkin myös täysin mahdotonta (tai liian tehotonta), mikä saattaa olla määräävä tekijä valintaa suoritettaessa 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 304

Esimerkki: henkilön isoäidin päättely vs. julistaminen attribuuttirakenteiden avulla <PERSON NAME="Jack" MOTHER="Jill"/> <PERSON NAME="Jill" MOTHER="Judith"/> vs. <PERSON NAME="Jack" MOTHER="Jill" GRANDMOTHER="Judith"/> <PERSON NAME="Jill" MOTHER="Judith"/> Hierarkkisten elementtirakenteiden syvyyteen joudutaan yleensä ottamaan myös kantaa. Vaihtoehtoja ovat - rekursiiviset elementtimallit ([recursive model]) - lapsielementit luettelevat elementtimallit ([specified model]) Esimerkki: rekursio vs. kiinteä hierarkia <!ELEMENT BOOK (SECTION)> <!ELEMENT SECTION (SECTION+ CONTENT)> vs. <!ELEMENT BOOK (SECTION)> <!ELEMENT SECTION (SUBSECTION+ CONTENT)> 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 305

Elementeistä, attribuuteista ja rakenteista Dokumenttirakenteita ja erityisesti tietue-elementtejä (komponentteja, informaatioyksiköitä) suunniteltaessa tyypillinen pulma on tiedon jakaminen järkevästi elementeiksi ja attribuuteiksi SGML määrittelee suuntaviivat jaolle näin: dokumentti on oltava luettavissa ilman tageja Perusjako: ominaisuus objekti ~ objekti ominaisuus Elementtien tyypillisiä ominaisuuksia: - hierarkkisuus, kertojat, paljon tekstiä, paloiteltava osiin (entiteetit), kirjoitetaan tekstieditorilla 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 306

Attribuuttien attribuuttien ominaisuuksia: - määre, oletusarvot, vähän tekstiä, annetaan Ominaisuudet-dialogin avulla Tiedon jako elementteihin ja attribuutteihin riippuu lopulta esim: - merkkauskäytännöstä esitetyistä toiveista (esim. joskus kaikki tieto halutaan esittää elementteinä) - dokumenttien esitysversioiden tuottamiseen liittyvistä rajoitteista (esim. CSS1 ei osaa esittää attribuutteja) - dokumenttiluokan määrittävän skeemaformalismin rajoitteista (esim. XML DTD:n avulla voidaan elementille sallia mv. määrä lapsielementtejä mutta ei attribuutteja) ja siis esimerkiksi XML-spesifikaation piirteistä (esim. jäsentämätöntä dataa käsitellään aina attribuutteihin liitettävien entiteettiviittausten perusteella) - muiden käytettävien ohjelmistojen rajoitteista (esim. ohjelma Z ei osaa käsitellä kaikentyyppistä attribuuttitietoa oikein) Sanaston (elementtien ja attribuuttien) nimien valintakriteereitä: systemaattisuus, termit yksikössä, kuvaavuus, vältä hankalia merkkejä, vältä helposti sekoittuvia merkkejä (ei ko, k0, jne) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 307

Tarkastellaan seuraavaksi tyypillisiä esimerkkitilanteita, joissa vertaillaan yksinkertaisia elementti- ja attribuuttirakenteita Esimerkki: dokumentissa on erilaisia luetteloita (nimiä, viikonpäiviä, kuukausia), joiden sisältönä on tekstiä Rakennevaihtoehdot: sisältöspesifi merkkaus vs. yleinen merkkaus 1) 2) PARENT PARENT PARENT PARENT + + + + NAME WDAY MONTH ITEM Sisältöspesifin merkkauksen hyvänä puolena on rakenteiden selkeys: eri asioille on omat elementtinsä huonoa taas se, että rakenteen erikoistapauksia tulee paljon (samanlaisilla rakenteilla on eri nimiä) Yleisen (geneerisen) merkkauksen hyvä puoli on tarpeettoman rakenteellisen toiston karsiminen huonoa taas se, että rakenteiden merkitys ei välttämättä ole suoraan merkkauksesta luettavissa 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 308

Pelkistetyn (huolimattoman) geneerisen merkkauksen erityisenä vaarana on informaation katoaminen (jos konteksti on tulkinnanvarainen) Tilannetta voidaan selventää rikastamalla rakennetta joko elementtien tai attribuuttien avulla Esimerkki: otsikkokentän lisääminen vs. luokittelu PARENT PARENT TITLE + ITEM + ITEM TYPE=(NAME DAY MONTH) Valinta perustuu taas sovelluskohtaisiin suunnitteluratkaisuihin. Tosin yo. tapauksessa attribuutin käyttö on ilmeisen huono ratkaisu, koska tyyppi on selvästikin sekvenssin (listan), eikä sen yksittäisen elementin ominaisuus (nyt sama attribuutti TYPE toistuu turhaan joka elementissä ITEM) Sekvensseille yhteisten ominaisuuksien määrittäminen tapahtuu yleensä luontevimmin (abstraktien) säilöelementtien ([container]) avulla. Ks. tapaus 1 seuraavassa kuviossa: 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 309

TAPAUS 1: TAPAUS 2: (TIETOA NÄKYVILLÄ ENEMMÄN) PARENT PARENT ID=ID LANG=(FI EN) RESOURCE=NMTOKEN? LIST + TYPE=(NAME DAY MONTH) LIST + TYPE=(NAME DAY MONTH) TITLE=CDATA ITEM ITEM ID=ID Elementin ominaisuuksien (attribuuttien) voidaan hyvin ajatella periytyvän puudiagrammin rakenteen mukaisesti elementin jälkeläisille: toistuva attribuuttitieto kannattaa siis merkitä puurakenteessa järkevästi mahdollisimman ylös (ks. yo. kuvion tapaus 2) Säiliöelementtien käyttö on erityisen perusteltua tilanteissa, jossa useita sekvenssejä liittyy samaan isäelementtiin Tyypillinen käyttötarkoitus säiliöelementeille on myös tilanne, jossa sekvenssit ovat kokonaan valinnaisia. Puuttuvan sekvenssin tapauksessakin saattaa olla tarkoituksenmukaista korostaa puuttuvan kohdan rakennetta 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 310

Esimerkki: Säiliöelementtien lisääminen on seuraavassa perusteltua sekä rakenteen selkeyttämiseksi että puuttuvan kohdan merkkaamiseksi: PARENT + * + DESC NAME DAY MONTH MEMO NOTES Nyt on mahdollista, että elementtejä DAY ei ole lainkaan. Jos sen sijaan valitaan PARENT + MONTH NAMELIST DAYLIST MONTHLIST + * + ITEM ITEM ITEM elementti DAYLIST näkyy vaikka päiviä ei dokumentin esiintymässä olisikaan 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 311

Säiliöelementit voivat olla luonteeltaan myös täysin konkreettisia - tyypillinen (tietokannan) suunnitteluvirhe onkin juuri tyhjien säiliöiden katoaminen Esimerkki: seuraavat varastot ovat toki olemassa vaikka ne olisivatkin tyhjiä (varastojen attribuutit tästä selvä merkki - ne voivat esimerkissä tosin puuttuakin) <STOCK> <WAREHOUSE ID="A1" COOLED="NO"> <ITEM TYPE="FISH" BOX="PLASTIC-D8" AMOUNT="45"> To be shipped as soon as possible! </ITEM> </WAREHOUSE> <WAREHOUSE ID="A2" COOLED="NO"></WAREHOUSE> </STOCK> Oikea malli olisi siis alla tapaus 1) mutta ei tapaus 2) (ei merkkausesimerkkiä): 1) STOCK + WAREHOUSE * ITEM ID=ID? COOLED=(YES NO) 2) TYPE=(FISH MEAT FRUIT) BOX=NMTOKEN AMOUNT=NMTOKEN STOCK * ITEM WH_ID=ID? WH_COOLED=(YES NO) TYPE=(FISH MEAT FRUIT) BOX=NMTOKEN AMOUNT=NMTOKEN 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 312

Miten kirjoitan hyvän dokumentin tyyppimäärittelyn? Perimmäiset hyvyyden kriteerit ovat tietenkin: 1) DTD toteuttaa määrittelytyön vaatimukset, 2) ratkaisut ovat selkeitä ja käytännössä toimivia DTD on kuitenkin vain osa työn tuloksesta. Hyvän dokumenttiluokan määrittelyn, kun minkä tahansa muunkin spesifikaation, ominaisuuksia ovat: 1) täydellisyys (kaikki asiaankuuluva määritellään ja kuvataan) 2) tarkkuus ja virheettömyys (ei väärinymmärtämisen mahdollisuutta eikä asiavirheitä) 3) ymmärrettävyys (esitys niin yksinkertaisesti ja havainnollisesti kuin mahdollista - sopusoinnussa täydellisyyden ja tarkkuuden kanssa) 4) testattavuus (mahdollisuus verifioida työtä läh. määrityksiin vedoten) 5) jäljitettävyys (mahdollisuus seurata määrityksiä suunnitteluvalintojen kautta toteutukseen ja päinvastoin) Huomaa, että työn loppudokumentoinnin tulisi sisältää teknisen dokumentaation ohella myös seuraavat osat: merkkauksen referenssimanuaali, käyttöohje ja ohjeet eri työkalujen käyttämiseksi 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 313

Hei, minun nimeni on Ossi. Olen tagien väärinkäyttäjä Hyväkään dokumenttiluokan ja merkkauksen suunnittelu ei auta jos elementtejä merkataan väärin eli vastoin niiden tarkoitusta (vrt. HTML) SGML-maailma tuntee termin TAS: Tag Abuse Syndrome (~tagien väärinkäyttösyndrooma). Väärinkäytön ominaisia piirteitä ovat: 1) tagien valinta niitä vastaavan elementin ulkoasun perusteella (esimerkki: merkataan HEAD3 kun tarkoitetaan vain vahvennettua tekstiä tai kirjoitetaan sivunumero elementin FOOTER sisään, koska näin se saadaan oikeaan kohtaan tulostetta) 2) jätetään käyttämättä spesifejä elementtejä kun niitä olisi saatavilla (esimerkki: kirjoitetaan kaikki aineisto elementteihin PARAGRAPH vaikka olisi saatavilla myös elementtejä DEFINITION, EXAMPLE, NOTE ja WARNING) 3) käytetään sekaisin eri merkkausta saman asian esittämiseen (esimerkki: käytetään toisinaan elementtiä QUOTE ja toisinaan EMPHASIS) 4) valitaan merkkaus väärin ymmärtämättä sen merkitystä (esimerkki: merkataan QUOTE kun oikeastaan pitäisi merkata DEFINITION) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 314

Tunnistatko omasi? Ongelmat ovat yleensä seurasta Dokumenttiluokan toteuttamisesta - yrityksestä ottaa käyttöön liian laaja tai rikas (=vaikea) merkkaus - huonosta merkkauksen dokumentoinnista - kiireestä, tietämättömyydestä tai välinpitämättömyydestä - merkkauskäytännön suunnittelu- ja toteutustyön suoranaisista virheistä On tärkeää huomata, että merkkausta pitää opiskella ja harjoitella, koska merkkauskäytäntö on välttämätöntä tuntea kokonaisuudessa etukäteen merkkauksen aloittamista jotta merkkaaminen olisi rikasta ja systemaattista Uudenlaista merkkausta ei opi samalla kun tekee ensimmäistä työtään, vaan ensimmäinen työ on aina harjoitustyö Hyvään merkkauskäytäntöön päästään yleensä vain riittävän ohjeistuksen ja harjoittelun avulla: - motivointi - riittävä dokumentointi ja käyttöesimerkit - koulutus ja harjoittelu (tämä pitää ottaa huomioon paitsi aikataulussa, myös dokumentaatiossa!) 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 315

Lopuksi: itsestäänselvyyksiä sikariportaalle TAS on todellinen ongelma, jolta välttäminen vaatii aktiivisia toimenpiteitä sekä työn tekijältä että työn organisoijalta. Jos tiedon merkkaus menee systemaattisesti pieleen, murenee tiedon rakenteellisuuden perusta kokonaan Dokumenttien merkkaaminen käsin ei yleensä ole tarkoituksenmukaista, vaan dokumenttiluokkien käyttö sidotaan yleensä joidenkin (XML-)editorien käyttöön Editorikaan eivät aina poista ongelmia (vaan pahimmillaan muuttavat ne vain toiseen muotoon). Vaikka pitkällä tähtäimellä rakenteellisuuteen siirtyminen tehostaisikin työskentelyä, lyhyellä aikavälillä (ylimenokaudella) työmäärä ja tarve uuden opiskeluun kasvaa Rakenteisten dokumenttien suunnittelun tuotosten käyttöönotto synnyttää yleensä muutosvastarintaa, jonka syinä voivat olla esim. - periaatteellinen vastarinta; esim. vastustetaan ylhäältä valmiina annettua toimintamallia (vaikka se olisi hyväkin) - lisääntynyt työmäärä, opiskelupaineet, muuttuva työympäristö ja turvallisista (tutuista) ja toimivista toimintamalleista luopuminen, muutosten kerrannaisvaikutukset 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 316

- uusien ratkaisujen lastentaudit tai kokonaiset suunnitteluvirheet - uusien ohjelmistojen puutteet ja uudenlaiset metaforat Ongelmia voidaan pyrkiä ennaltaehkäisemään ja ratkomaan ennen kaikkea: 1) antamalla kaikille toimijoille vaikuttamisen mahdollisuuksia suunnitteluprosessissa tai vähintäänkin tiedottamalla asioista hyvin 2) huomioimalla ylimenokausi resursseissa (koulutuksen järjestäminen ja hyväksymällä väliaikaisesti(?) alentunut työteho) 3) kuuntelemalla kritiikkiä ja muutosehdotuksia sekä kehittämällä työskentelytapoja tämän perusteella (jälkimmäinen unohtuu helposti ) Työtapoja suunniteltaessa (ja henkilökuntaa kouluttaessa) kannattaa systemaattisesti pitää kiinni tiedon rakenteistamisen punaisesta langasta. Huonoin toimintamalli on sellainen, jossa kirjoittajat ensisijaisesti muokkaavat dokumenttien esitysversioita ja päivittävät lähdedokumentteja kun ehtivät: OIKEIN: SISÄLLÖN PÄIVITYKSET LÄHDE- DOKU- MENTTI AUTOMATISOITU JULKAISUPROSESSI WWW-SIVU PAINOTUOT- TEEN LADONTA VÄÄRIN: SISÄLLÖN PÄIVITYKSET 73275 RAKENTEISET DOKUMENTIT (kevät 2004) luentorunko ON & JH 317