Menetelmäohje Dokumenttien hallinta

Transkriptio

1 Menetelmäohje Dokumenttien hallinta

2 Sisällysluettelo 1. Johdanto Termit ja määritelmät Henkilöt ja roolit Työkalut Menetelmät Kirjoittaminen yleisesti Kirjoittaminen prosessina Tiedostojen nimeäminen Dokumentaation kieli Dokumenttien luottamuksellisuus Tiedostoformaatit Dokumenttien hallinta Dokumentin elinkaari Dokumentin luominen Vedos Kommentointi Hyväksyntä Arkistointi Tuhoaminen Versionhallinta Versiohistoria -taulukko Julkaisujärjestelmä CVS - Concurrent Versions System Dokumenttipohjat Yleiset dokumenttipohjat Yleinen dokumenttipohja - MS Word Kokousmuistio - MS word Esityspohja - MS PowerPoint Tietotekniikkaprojektien dokumenttipohjat Vaatimusmäärittely - MS Word Käyttötapausmäärittely - MS Word Toiminnallinen määrittely - MS Word Tekninen määrittely - MS Word Muuta...15 Menetelmäohje: Dokumenttien hallinta 2

3 Versio- ja muutoshistoria Versio Päiväys Tekijä Kuvaus Tapio Nissilä Ensimmäinen luonnos Tapio Nissilä Muutoksen kommenttien perusteella ja dokumenttipohjien päivittäminen Tapio Nissilä Muutokset nimeämiskäytäntöön Tallennettu: :43 Tulostettu: :13 Menetelmäohje: Dokumenttien hallinta 3

4 1. Johdanto Tässä dokumentissa on kuvattu dokumentaation hallinnan työkalut, menetelmät sekä dokumenttien elinkaari. Tämän ohjeen tarkoituksena on luoda yhdenmukainen käytäntö dokumentaation tuottamiselle. Dokumentaatiota tehdään asiakkaan ja toimittajan välisen kommunikaation selkiyttämiseksi sekä asioiden sopimiseksi. Projektityössä dokumentaation tekoon osallistuu useita henkilöitä samanaikaisesti, ja dokumentaation määrä kasvaa usein huomattavan suureksi projektin kuluessa. Tämän takia on olemassa tarve prosessille ja yhdenmukaiselle työkalujen käytölle. Menetelmäohje: Dokumenttien hallinta 4

5 2. Termit ja määritelmät Tässä kappaleessa esitellään keskeisimmät termit ja määritelmät joita käytetään dokumentaation hallinnassa Henkilöt ja roolit Seuraavassa taulukossa on esitelty tärkeimmät roolit joita dokumentaation tuottamisessa osallistuu. Henkilö tai rooli Omistaja Kommentoija Hyväksyjä Kuvaus Henkilö jonka vastuulla tietyn dokumentin kirjoittaminen on. Henkilö, joka osallistuu dokumentin tuottamiseen kommentoimalla dokumentin sisältöä, oikeinkirjoitusta tai ulkoasua. Henkilö, jolla on projektissa oikeus hyväksyä dokumentteja. Muodollinen hyväksyntä järjestetään, jotta dokumentit luetaan riittävän monta kertaa ennen jakeluun päästämistä Työkalut Tässä kappaleessa on esitelty projektissa käytettävät ohjelmistot sekä näiden versiot. Työkalu Microsoft Word 2000/XP Microsoft PowerPoint 2000/XP Kuvamateriaali Adobe PDF Writer Kuvaus ja käyttötarkoitus Tekstinkäsittelyohjelmalla tuotetaan kaikki tekstimuotoinen dokumentaatio. Tiedostoformaattina käytetään Word 2000:n dokumenttiformaattia. Tiedostot luodaan käyttämällä tässä dokumentissa liitteenä olevia dokumenttipohjia. Esitysgrafiikkaohjelmalla tuotetaan kaikki esitykset kokouksiin, projektipalavereihin sekä katselmuksiin. Tiedostoformaattina käytetään PowerPoint 2000:n dokumenttiformaattia. Tiedostot luodaan käyttämällä tässä dokumentissa liitteenä olevia dokumenttipohjia. Kuvamateriaali tuotetaan gif, jpg tai png formaateissa käyttäjän parhaaksi katsomilla välineillä. tulostinohjelmistoa käytetään pdf-formaattia olevien tiedostojen tuottamiseen. PDFWriterin käyttö tapahtuu asentamalla se työasemaan tulostimeksi, jolloin korvertoitava tiedosto tulostetaan Wordistä tai PowerPointista PDF Writerin kautta tiedostoksi Menetelmät Menetelmät ovat projektissa käytettäviä toimintatapoja ja ohjeita joiden noudattaminen on välttämätöntä sujuvan työskentelyn takaamiseksi. Menetelmäohje: Dokumenttien hallinta 5

6 Kirjoittaminen yleisesti Dokumentaation tuottaminen on sekä ryhmätyötä että yksilö suoritus. Jotta dokumentointi etenisi selkeästi ja jouhevasti, sovelletaan siinä vastuujakoa. Jokaisella dokumentilla on oltava selkeä tarkoitus. Dokumentin sisältö syntyy faktoista sekä projektissa sovituista ja päätetyistä asioista. Päätösten tekoon osallistuu useita ihmisiä, kun taas lopullisen dokumentin tuottamisen tekee pääasiassa yksi henkilö. Jokaisesta projektissa tuotettavasta dokumentista vastaa yksi nimetty henkilö (dokumentin omistaja). Tämän henkilön vastuulla on dokumentin valmistuminen. Hän luo dokumentin ja kirjoittaa siitä suurimman osan. Tämä lisäksi dokumentin tekoon voi osallistua muita henkilöitä. Näitä ovat asiakkaat, asiantuntijat sekä kirjoittamiseen osallistuvat henkilöt kuten kommentoija ja hyväksyjä. Kieliasun tulee olla asiallinen ja selkeä. Tavoitteena on asiallinen kielellinen ilmaisu. Tarkoituksena ei ole kuitenkaan jäykkä kirjakieli, joten omaa harkintaa saa käyttää. Huomioitavaa on, että usein dokumentaatiota lukevat myös projektin ulkopuoliset henkilöt, jolloin kieliasun pitää kestää myös tämä. Liian yleisellä tasolla olevia sanontoja pitää välttää. Yleisimpiä virheitä ovat sanonnat jotka eivät tarkoita mitään, esim. Tavoitteena on tehdä mahdollisimman hyvä järjestelmä. Sana mahdollisimman on huono, koska sen sisältöä ei ole määritelty. Toinen yleinen virhe on tekstin huono hyötysuhde. Usein dokumentaatiossa on oleellisen asian lisäksi paljon tarpeetonta tekstiä. Lyhyt ja ytimekäs ilmaisu on lukijalle selkeintä Kirjoittaminen prosessina Kirjoittaminen alkaa hahmottelemalla sisällysluettelo. Tämän jälkeen jatketaan kirjoittamalla dokumentin tarkoitus ja tavoite. Näin dokumentin kirjoittaminen helpottuu itse kirjoittajalle, kun tehtävä on sisällysluettelon avulla jaettu pienempiin osiin, ja dokumentin tavoite on selkeästi kirjoitettu. Kun kirjoittaminen on edennyt (esim. 80/20 -säännön mukaan) niin pitkälle, että dokumentin valmistuminen edellyttää toisten henkilöiden kommentteja, tekee dokumentin omistaja dokumentista vedoksen. Vedokseen hän kerää kommentit yhdeltä tai useammalta henkilöltä. Tämän jälkeen omistaja huomioi kommentit ja jatkaa dokumentin kirjoittamista. Vedos -kierroksia voidaan järjestää useampia, yleensä korkeintaan kolme on riittävästi. Menetelmäohje: Dokumenttien hallinta 6

7 Kun kirjoittaja on saanut dokumentin valmiiksi, tapahtuu dokumentin hyväksyminen. Tällöin projektipäällikkö tai vastaava henkilö hyväksyy dokumentin, jonka jälkeen se on valmis siirrettäväksi jakeluun. Kun dokumentti on toimitettu asiakkaalle, se on niin sanotusti jakelussa. Tällöin sen muokkaaminen ja edelleen kehittäminen tehdään yhteistyössä asiakkaan kanssa Tiedostojen nimeäminen Tiedostojen nimissä ei saa käyttää ä, ö, å kirjaimia. Tämä siksi, että se mahdollistaa tiedostojen lähettämisen sähköpostilla erilaisten tietojärjestelmien välillä. Tiedostot tulee nimetä havainnollisesti siten, että nimestä käy ilmi tiedoston sisältö. Tiedostonnimi jakautuu kolmeen merkitsevään osaan seuraavasti: 1) dokumentinnimi 2) versionumero 3) tiedostopääte Esimerkki: vaatimusmaarittely05.doc Näiden osien järjestys on määrätty, sillä kun versionumerointi pidetään viimeisenä, saadaan tiedostojärjestelmän hakemistolistauksesta jokaisen dokumentin kaikki versiot järjestyksessä. Näin yhdessä hakemistossa voidaan pitää useammasta dokumentista kaikki versiot ja käsitellä tätä tietomäärää suhteellisen helposti. Mikäli dokumentaatiota käytetään ilman dokumenttienhallintajärjestelmää (kuten CVS), tulee dokumentin nimessä ylläpitää versiointia. Tämä tehdään vähintään kaksi numeroisella juoksevalla numeroinnilla. Kaksi numeroinen mahdollistaa 100 versiota dokumentista, joten käytännössä sen pitäisi riittää hyvin pitkälle. Kaksi numeroa on välttämätöntä myös käyttöjärjestelmän hakemistolistauksen takia. Numerointi (00 99) tapahtuu seuraavasti: projektisuunnitelma03.doc. Mikäli projektissa on selkeästi vaiheita, voidaan vaiheet ottaa mukaan tiedostojen nimeämiseen. Tällöin dokumentin versionumeron yhteyteen liitetään tieto vaiheesta. Menetelmäohje: Dokumenttien hallinta 7

8 Esimerkkinä projektisuunnitelma projektin 1. vaiheesta, versio 08: projektisuunnitelma01.08.doc tai vaatimusmaarittelyt2.12.doc. Mikäli projektissa tehdään järjestelmä, joka jakautuu moneen itsenäiseen osaan, syntyy dokumentaatiota hyvin suuri määrä. Tällöin dokumentit tulee nimetä siten, että jokaisen dokumentin nimestä käy ilmi, mitä järjestelmän osaa se koskee. Järjestelmän osat nimetään seuraavasti: Koordinaattieditori: Ohjelma-aika komponentti: Koordinaattilukija: EDI OAK KLU Esimerkki tiedostojen nimeämisestä: EDI_toiminnallinen_maarittely.05.doc. Tällöin tiedoston nimestä käy ilmi sisältö (toiminnallinen määr.), järjestelmän osa (EDI), versio (05) sekä tiedostotyyppi (doc). Joskus saattaa olla tarpeellista käyttää lisäksi juoksevaa numerointia tiedostojen identifioinniksi. Tällöin tiedostot ja tunnisteet liitetään toisiinsa taulukolla (esim. projektisuunnitelma), ja edellisen esimerkin toiminnallinen määrittely olisi tällöin esim. EDI02_toiminnallinen_maarittely.05.doc, jolloin tiedoston identifioiminen tapahtuu EDI02 osion avulla Dokumentaation kieli Kaikki projektin dokumentaatio tehdään pääsääntöisesti yhdellä kielellä. Projektin alussa sovitaan kirjallisesti (projektisuunnitelmassa) mikä on projektin kieli. Projektisuunnitelmassa voidaan myös erikseen sopia, mikäli joku sidosryhmä tarvitsee dokumentaation jollakin projektista poikkeavalla kielellä. Tällöin on sovittava erikseen, miten ja kuka kieliversion tuottaa. Huomioitava mahdolliset lisäkustannukset sekä aika joka tarvitaan kieliversioiden tuottamiseen Dokumenttien luottamuksellisuus Luottamuksellisuus on kaiken yhteistoiminnan perusta. Dokumentaation, kuten kaiken muun projektin informaation, luottamuksellisuudesta ja julkisuusasteesta sovitaan erikseen kirjallisesti. Tämän jälkeen on mahdollista toteuttaa dokumentaation osalta sovittu luottamuksellisuus tietotekniikan sekä työmenetelmien keinoin. Dokumentteja käsitellään ja hallintaan siten, että ulkopuoliset eivät pääse käsiksi niihin missään tilanteessa. Menetelmäohje: Dokumenttien hallinta 8

9 Tiedostoformaatit Projektissa käytetään vain tiettyjä tiedostoformaatteja. Dokumenttien editoimiseen ja työstämiseen käytetään käytettävien ohjelmistojen käyttämiä formaatteja (Word, PowerPoint, jne). Dokumenttien julkaisuun käytetään PDF- ja HTML-formaatteja. Kaikki julkaistavat dokumentit tehdään pääsääntöisesti PDF formaatissa. Tämä siksi, että ulkoasun ja muotoilu ovat täysin kontrolloitavissa PDFformaatissa. Toinen syy on HTML-kielin monimuotoisuus sekä yhteen dokumenttiin mahdollisesti liittyvien *.css ja *.xml tiedostojen käsittelyn vaikeudet. HTML-formaatti on julkaisuille toissijainen formaatti eikä sen käyttöä suositella. Menetelmäohje: Dokumenttien hallinta 9

10 3. Dokumenttien hallinta Dokumenttien hallinnan tavoitteena on, että jokainen projektiin osallistuva henkilö löytää haluamansa dokumentin oikean version nopeasti ja miellyttävästi. Dokumenttien hallinta liittyy myös tietoturvan toteutukseen. Dokumenttien hallinta sisältää dokumentin luomisen, kirjoittamisen, arvioimisen, hyväksynnän sekä tuhoamisen. Dokumentin elinkaaren hallintaan liittyy myös version hallinta (seuraava kappale) Dokumentin elinkaari Tässä kappaleessa hahmotellaan dokumentin elinkaari sen luomisesta julkaisuun sekä arkistointiin Dokumentin luominen Dokumentin kirjoittaminen aloitetaan luomalla uusi dokumentti projektissa käytettävien dokumenttipohjien perusteella. Kun dokumentin kirjoittaminen on aloitettu, kutsutaan dokumenttia vedokseksi Vedos Vedos on nähtävillä projektiryhmälle, mutta ei asiakkaalle tai projektin ulkopuolisille henkilöille. Vedoksen tiedostoformaatti on dokumentin työstöön käytetty formaatti Kommentointi Kun omistaja on kirjoittanut dokumenttia johonkin vaiheeseen, järjestää omistaja vedokselle kommentoinnin. Tällöin kommentoija lukee vedoksen ja kommentoi sitä kirjallisesti. Kommentointi tehdään aina kirjallisesti. Omistaja käy läpi kaikki kommentit ja tekee näitä vastaavat muutokset oman harkintansa mukaisesti. Kommentointikierroksia voidaan tarvittaessa järjestää useampia Hyväksyntä Kun dokumentti on kirjoittajan mielestä valmis, se hyväksytään. Hyväksyntä tapahtuu siten, että hyväksyjä lukee dokumentin ja varmistuu sen sisällön ja ulkoasun oikeellisuudesta. Hyväksynnän tarkoituksena on varmistaa että useampi henkilö on lukenut dokumentin ennen sen julkaisua. Hyväksynnän jälkeen dokumentti voidaan laittaa jakeluun. Menetelmäohje: Dokumenttien hallinta 10

11 Arkistointi Kun dokumentin sisältö on vanhentunutta eikä sitä aktiivisesti tarvita, arkistoidaan dokumentti Tuhoaminen Dokumenttien tuhoaminen on hyvin poikkeuksellista. Yleisenä periaatteena on, että mitään dokumentaatiota ei tuhota, vaan kaikesta tehdään uusi versio, jolloin vanha jää käyttämättömänä talteen. Tuhoaminen tapahtuu vain mikäli tähän on painavia syitä, kuten asiakkaan toivomus. Menetelmäohje: Dokumenttien hallinta 11

12 4. Versionhallinta Versionhallinnan tavoitteena on mahdollistaa dokumenttien muutoshistorian seuraaminen. Projektissa on yleensä useita henkilöitä jotka osallistuvat dokumentaation tuottamiseen. Tällöin on erittäin tärkeää tietää miten dokumentteja on muokattu ja kenen toimesta. Versionhallinta toteutetaan sekä työmenetelmänä että ohjelmistoteknisin apuvälinein Versiohistoria -taulukko Dokumenttipohjissa on versiohistoriataulukko. Käyttäjä päivittää dokumenttiin tekemänsä muutokset taulukkoon ennen tiedoston tallentamista Julkaisujärjestelmä Digitv-synkro.org osoitteessa on dokumenttien julkaisujärjestelmä. Tämä mahdollistaa dokumenttien jakamisen julkisessa internetissä. Jokaisella projektin henkilöllä on pääsy järjestelmään. Järjestelmän avulla on mahdollista julkaista dokumentteja. Järjestelmä ei mahdollista kehittyneitä dokumenttien hallinnan ominaisuuksia, kuten tiedostojen check-in, check-out, lukitseminen, piilottaminen, jne. Mikäli näitä tarvitaan, on otettava käyttöön joku dokumenttien hallintajärjestelmä kuten esim. CVS CVS - Concurrent Versions System CVS on versionhallintatyökalu. Se mahdollistaa sekä dokumentaation että ohjelmistojen lähdekoodin versioinnin. CVS:n toiminta perustuu siihen, että se tallentaa vain muutokset suhteessa edelliseen versioon, jolloin tarve kaikkien versioiden tallentamiseen poistuu. Tämä säästää levytilaa huomattavasti. Menetelmäohje: Dokumenttien hallinta 12

13 5. Dokumenttipohjat Tässä kappaleessa on dokumenttipohjat sähköisessä muodossa. Mikäli pohjiin tehdään muutoksia, tulee muutetut pohjat tallentaa tänne sekä päivittää tehdyt muutokset Yleiset dokumenttipohjat Yleiset dokumenttipohjat ovat yleiskäyttöisiä, jolloin ne sisältävät pääasiassa vain muotoilun sekä joitakin näppäinoikoteitä. Wordin makrojen käyttämistä pyritään välttämään toimintavarmuuden ja turvallisuuden nimissä Yleinen dokumenttipohja - MS Word Yleinen dokumenttipohja.dot Yleistä dokumenttipohjaa voidaan käyttää suunnitelmien, raporttien, jne. tekemiseen. Dokumenttipohjaan on tehty valmiit muotoilut seuraaville tekstityypeille. Lisäksi dokumenttipohjassa on muutoshistoria taulukko, sisällysluettelo, sivunumerointi sekä kansilehti. Tyyli Kuvaus Näppäinoikotie Heading 1 Päätason otsikko, sivun vaihto ennen Alt + 1 Heading 2 Toisen tason otsikko, ei sivun vaihtoa Alt + 2 Heading 3 Kolmannen tason otsikko, ei sivun vaihtoa Alt + 3 Normal Leipäteksti Alt + n Header Ylätunniste, pienempi kirjasinkoko - Footer Alatunniste, pienempi kirjasinkoko Kokousmuistio - MS word Kokousmuistio.dot Kokousmuistiopohjaa käytetään kaikkien kokousmuistioiden kirjoittamiseen. Menetelmäohje: Dokumenttien hallinta 13

14 Kokousmuistio perustuu yleiseen dokumenttipohjaan, mutta sisältää sen lisäksi kaksi taulukkoa, toisen kokouksen yleisiä tietoja varten ja toisen kokouksessa päätettyjä asioita ja näistä vastaavia henkilöitä varten Esityspohja - MS PowerPoint Esityspohja.pot Esityspohjaa voidaan käyttää kaikkien esitysten tekoon. Pohjaan on määritelty värit, logot, kirjasintyylit sekä asettelu Tietotekniikkaprojektien dokumenttipohjat Tässä kappaleessa on esitelty tietotekniikkaprojekteille tarkoitetut dokumenttipohjat. Nämä pohjat perustuvat yleisiin dokumenttipohjiin, mutta sisältävät lisäksi taulukoita sekä muita tietotekniikkaprojekteille tarkoitettuja ominaisuuksia. Dokumenttipohjia lisätään tänne projektin kuluessa Vaatimusmäärittely - MS Word Vaatimusmäärittelypohja perustuu yleiseen dokumenttipohjaan johon on lisätty vaatimusmäärittelyä varten taulukkoja Käyttötapausmäärittely - MS Word Toiminnallinen määrittely - MS Word Tekninen määrittely - MS Word Menetelmäohje: Dokumenttien hallinta 14

15 6. Muuta Muita huomioita ei tässä vaiheessa ole. Menetelmäohje: Dokumenttien hallinta 15