21.03.2018 / Nanni Koski

Lyhenteiden viidakossa kehitin itselleni muistukseksi uuden: DBD. Mistä tämä sitten on lyhennys? Käydään ensin katsomassa Googlesta, jos satuttiin osumaan johonkin nuorison käyttämään hypetermiin. Itse asiassa Urban Dictionaryn kaksi ylintä termiä sopii teemaan, joten pidetään vielä jännitystä yllä.

 DBD = ”Damn, bro, damn”

Yleensä käytetty ilmaisemaan ilmeisesti vaikuttuneisuutta, mutta tässä tapauksessa toi mieleeni päivän, joka tuntui data scientistin painajaiselta. Olen erityisen ihastunut kreikkalaisiin aakkosiin, joten otetaan ne mukaan selventämään tilannetta. Eli latinalaiset aakkoset viittaavat tunnettuihin asioihin ja kreikkalaiset johonkin tuntemattomaan, mikä ei suorilta ole selvää. Sanottakoon, että projektin vetohahmo sattui olemaan tänä päivänä lomalla, mikä lisäsi tulevan tehtävän haastetta.

Tehtävä: Asiakas A lähettää Excel-tiedoston B, jonka välilehdistä osalla, merkitään [math] \alpha_1, \ldots, \alpha_\beta [/math]  on tietoja, jotka tulee päivittää tiedostoon / tiedostoihin [math] \gamma_1, \ldots, \gamma_\delta [/math] kansiossa [math] \varepsilon [/math] palvelimella [math] \zeta [/math] ja sen jälkeen ajaa tauluihin [math] \eta_1, \ldots, \eta_\theta [/math] kannassa [math] \iota [/math] latauksilla [math] \kappa_1, \ldots, \kappa_\lambda [/math].

Juuri niin helppoa kuin se ääneen luettuna kuulostaa olevan.

Vaikea palapeli

Ehkä tunnin työ, jos kreikkalaisten aakkosten merkitys tässä kontekstissa on tuttu. Jos selvittäminen vaatii valistuneita arvauksia, niin tällaista ongelmaa ei ratkaista googlettamalla.

Tästä päästään sanakirjan seuraavaan ehdotukseen:

DBD = ”Don’t be Dumb”

Sanonnan kirjaimellinen käännös sopii aiheeseen paremmin kuin tarkoitettu ”Don’t worry”. Eli älä ole typerä – dokumentoi tekemisesi.

Mitä uusia muuttujia dataan luotiin, miksi ja millä tavalla? Rajattiinko osa havainnoista tarkastelun ulkopuolelle? Toki osa asioista on haastavampia dokumentoida. Ja joskus vasta kokeilut osoittavat, mikä toimii ja mikä ei. Ja kyllähän sen muistaa, miksi koodi meni näin ja missä järjestyksessä eri tiedostot tulee ajaa. Se on selvää, että tämä koodi löytyy täältä kansioista. Ja tuo tiedosto valitaan tässä tietyssä tilanteessa. Ja se päivitettävä osio koodissa on juuri tuo. Ja että jos haluaa saada aikaan tämän, niin käy muuttamassa tuolla valikossa arvoja. Niin ja muuttujien datatyyppien muunnokset pitää ottaa huomioon. Mutta sehän on selvää tulevan virheilmoituksen perusteella, jos sen sattuu saamaan. Eikö vaan?

Liian monta sekavaa ohjetta

No ei.

Miksi, mitä, miten ja mihin siis dokumentoida? Ja se tärkein eli:

Kuka? Sinä, juuri sinä. Just do it.

Mitä? Ajatukset ja toteutukset projektiin liittyen.

Miksi? Asiantuntemus. Muistipaikkojen vapauttaminen omasta päästä. Lähimmäisenrakkaus. Sharing is caring. Ja ehkä silloin saa viettää jonkun lomapäivän tarvitsematta vastata yhteenkään työpuheluun.

Miten? Tiimin / Asiakkaan saataville. Vaikka Wordillä, PowerPointilla, Notepadilla, R Markdownilla tai Trelloon.

Mihin? Dokumentoinnista ei ole hyötyä, jos sitä tarvitseva ei sitä löydä. Eli varmista, että tiimille on selvää, mistä työsi hedelmät on poimittavissa muidenkin iloksi.

Ehkä suurin ongelma dokumentoinnissa on kuitenkin se, kun into lähtee lapasesta ja perille pääsee nopeammin raskaalla kaasujalalla kuin jokaisen taukopaikan kautta. Kun tässä eräänä päivänä lisäilin koodin joukkoon jälkikäteen selityksiä siitä, miksi olin muokannut dataa esitetyllä tavalla, totesin, että eipä olisi ollut suuri vaiva kirjoittaa ne jo tehdessä.

DBD = ”Document before Doing”

Tästä eteenpäin pyrin seuraavaan: Sunnittele – kirjoita ylös – tee – vaikutu tuloksista tai yritä uudestaan. Sitä tarkoittaa minun DBD. Ihan aina ei (ehkä) ole mahdollista kirjoittaa suunnitelmia ja toteutuksia ylös ennen tekemistä.  Ja joskus on hyvä työskennellä flown mukana. Mutta tavoitteena on selvät ohjeet tai muistiinpanot edes kaikesta lopputuloksen kannalta oleellisesta tai toimivan tuotteen toiminnasta. Ehkä sitten pääsee käyttämään ensimmäistä fraasia alkuperäisessä tarkoituksessa.

Suuri vaikuttuneisuuden huudahdus: Wow!

Pahimmassa tapauksessa dokumentoinnin puuttuminen aiheuttaa moninkertaisen työn siihen vaivaan verrattuna, että asiat voi käydä tarkistamassa jostain. Datamuokkauksien tekeminen uudelle dataversiolle ajamalla siistit koodit läpi mahdollistaa useamman päivän työn tekemisen muutamassa minuutissa.

Mielelläni kuulisin lukijoiden kokemuksia toimivasta tai ei niin toimivasta dokumentoinnista. Tai jäikö jotain oleellista puuttumaan?

Tästä on hyvä siirtyä kahden viikon lomalle. Toivottavasti kaikki tieto on saatu välitettyä työkavereiden ulottuville ja löydettäväksi eivätkä päivät kaadu piilotteleviin dokumentaatioihin. Tai siihen minulle ihan itsestään selvään asiaan. Bye!


11.11.2013 / Jani Liimatta

Pahoittelut etukäteen blogimme lukijoille; tämä menee nyt hieman tuotemainoksen puolelle, mutta nyt on kyseessä sen verran uniikki tuote että on pakko hieman hehkuttaa.

Business Intelligence-projektit ovat tyypillisesti haasteellisia dokumentoitavia. Täytyy myöntää että itsellekin on useamman kerran tullut tunnettua tuskaa dokumentaatiota tehdessä toimituksen viime metreillä.

Tyypillisesti projektin dokumentaatio koostuu osin tehdystä määrittelydokumentista, jota sitten projektin edetessä täydennetään BI-projektin tuotoksilla (suomeksi, yleensä dokumentaatio luodaan vasta kun on ihan pakko).

Tyypillistä on, että Word-dokumenttiin luodaan n kpl staattisia taulukoita, joihin otetaan sisältöä sivumäärän kasvattamiseksi copy-pastella luodusta tietovarastosta, taulujen rakenteesta, stage-tauluista, kuutioista, mappauksista jne. Lopputuloksena on pahimmillaan sata sivua pitkä arvoton copy-paste-pläjäys.

Kahden vuoden kuluttua projektin päättymisestä ja dokumentaation luovuttamisesta on tyypillistä että:

  • Dokumentaatio on jäänyt päivittämättä ja on siksi käyttökelvoton.
  • Dokumentaatio on niin kompleksinen, pitkä ja tekninen, ettei asiakas ymmärrä siitä mitään. Dokumenttia ei ole edes avattu luovuttamisen jälkeen.
  • BI-projekti on enemmän tai vähemmän itse itsensä dokumentoiva, kokeneille tekijöille asiat selviävät helpommin katsomalla tuotokset läpi.
  • Dokumentaatio ei itse asiassa vastaa seuraaviin oleellisiin kysymyksiin:
    • Mistä raportilla näkyvä luku tulee? Missä se on tietovarastossa? Mistä lähdejärjestelmän taulusta ja sarakkeesta se tulee?
    • Miten raportit, kuutiot, tietovarastot suhteutuvat toisiinsa?
    • Mitä tapahtuu jos muutan tietovaraston yhden taulun tai sarakkeen nimeä tai tietotyyppiä, mihin kaikkialle se vaikuttaa?

Dokumentaation suurin arvo on siihen tallennetut käyttäjätunnukset ja salasanat, joilla pahimmillaan pääsee sekunneissa murtautumaan asiakkaan tuotantoympäristöön. Varmuuden vuoksi dokumentaationivaska kulki konsultin mukana putkikassissa, joka unohtui epähuomiossa Ala-Tikkurilan Shell-huoltoasemalle.

Näitä dokumentoinnin dilemmoja olen silloin tällöin pohdiskellut jo monta vuotta. Muistelisin että kymmenisen vuotta sitten eräs kollega heitti idean, mitä jos oikeasti dokumentoitaisiin projekti mappauksilla? Siten että helposti päästäisiin käsiksi esim. raportin sarakkeelta tiedon lähteelle asti? Taisin vastata jotain tyyliin: “Joo, tee pois vaan – jos osaat”. No, ilman työkaluja tuollaisen dokumentaation luonti olisikin ollut mahdoton tehtävä.

Vuosi sitten törmäsin Pragmatic Worksiin. ‘BI Documenter’ (nykyiseltä nimeltään Doc xPress)-tuotteeseen.  Olin myyty heti ensiasennuksen suoritettuani.

Yhtään liitoittelematta uskallan väittää, että Doc xPress vie BI-projektin dokumentoinnin uusiin, ennennäkemättömiin svääreihin.

Lyhyesti, kyse on tästä:

  • Dokumentaation automatisointi. Dokumentoi Microsoft BI-ympäristösi automaattisesti Word, HTML tai .chm-help-file muotoisena. Unohda rakenteiden manuaalinen kopiointi. Dokumentaatio on käytettävyydeltään aivan toista luokkaa staattiseen word-dokumentaatioon verrattuna, ja aina ajantasainen.

Document

  • Projektin seuranta projektin aikana; mitä on saatu aikaiseksi. Tämä onnistuu Snapshot-vertailulla. Dokumentaation versiot arkistoidaan automaattisesti snapshotteina. Näet työkalun avulla heti mitä uutta projektiin on tullut esim. edellisen viikon aikana. Alla olevan esimerkkivertailun avulla selviää, että asiakasdimensioon on lisätty yksinkertainen audit-toiminnallisuus.
Valitse vertailtavat SnapHotit
Valitse vertailtavat SnapShotit
Vertaile versioita
Vertaile eri SnapShot-versioita
  • Ehkä paketin pysäyttävin ominaisuus on Lineage Analysis. Koskaan aiemmin ei ole ollut käsissä välinettä, jolla pystytään analysoimaan projektin vaikutussuhteita miltä tahansa tasolta. BI-projektin kokonaisuushan koostuu tyypillisesti ETL:stä, tietovarastosta, kuutioista sekä raporteista. Lineage Analysis mahdollistaa ennennäkemättömällä tavalla valitsemaan esimerkiksi tietovarastosta yhden sarakkeen, selvittämään mistä se tulee ja mihin sarake ui kuutiossa ja raporteilla.
  • Erilaisia hyötyjä voidaan esimerkiksi saada:
    • Vaikutussuhteiden selvittäminen pääkäyttäjälle ja kehittäjille – esim. mistä lähteestä raportilla näkyvä luku tulee, mitä ketjua pitkin se tulee raportille
    • Projektin kokonaisuuden hahmottaminen uudelle kehittäjälle
    • Mihin kaikkialle vaikuttaa jos vaihdan tietovaraston sarakkeen tietotyyppiä tai nimeä
    • Heikot nimeämiskäytännöt  tietovarastossa paljastuvat projektipäällikölle tai pääkäyttäjälle helposti ja nopeasti. On tyypillistä että kehittäjien laiskuuden vuoksi ETL-komponentit, datasetit jne on jätetty nimeämättä. Tämä vaikeuttaa ylläpitoa tai uusien kehittäjien mukaan hyppäämistä huomattavasti. Tai esimerkiksi asioita on oiottu lisäämällä logiikkaa  pelkästään kuutioon.
    • Alla olevasta esimerkistä selviävät nopeast demo- BI-projektin komponentit, joissa asiakasdimensiota on käytetty:

Lineage Analysis käsitetasolla

  • Seuraavasta esimerkistä selviää, mistä lähdejärjestelmän sarakkeesta asiakkaan nimi tulee. Se on näemmä yhdistelmä lähdejärjestelmän etu- ja sukunimestä.

LineageAnalysis saraketasolla