Opetushallituksen kaikki palveludokumentaatiot tulisi kerätä yhteen paikkaan yhdenmukaisesti kuvattuna. Alla palvelukorttipohja, jonka voi kopioida omalle palvelusivulle tällä wikisivustolla. Jos tarvitset ohjeita wikin hallintaan, ota yhteys tietohallintoon (jatkuvatpalvelut@oph.fi).
Ohjeita palvelukortin ylläpitoon
Tiedot tallennetaan alla olevan palvelukortin esimerkkien mukaisesti. Tiedot tulisi päivittää vähintään kaksi kertaa vuodessa. Palvelun tyyppi on substanssipalvelu, kun kyseessä on rajattuun tarkoitukseen toteutettu palvelu ja sitä eivät tyypillisesti hyödynnä muut palvelut. Substanssipalvelun omistaa asiakasyksikkö ja yleiskäyttöiset palvelut omistaa tietohallintoyksikkö ja niiden tehtävä on palvella useiden Opetushallituksen prosessien toiminnallisia tarpeita.
Palvelukorttiin voi liittää monenlaisia näkymiä käyttämällä wikistä löytyviä "makroja", jolloin vältytään tiedon tallentamisesta useaan kertaan. Esimerkkipalvelukortilla on esimerkkejä makrojen käytöstä.
Palvelukortin suhde järjestelmäsalkkuun
Palvelukortti ja järjestelmäsalkku eivät sulje toisiaan pois. Palvelukortin tarkoitus on kuvata palveludokumentaatio, eli palveluun liittyviä käytännön asioita ja teknistä näkökulmaa kun taas järjestelmäsalkussa näkökulma on hallinnollinen. Siellä kuvataan mm. kustannuksiin, käyttäjärooleihin ja ylläpitoon liittyviä tietoja. Palvelukortin tarkoitus on myös palvella Opetushallituksen ulkopuolisia toimijoita ja tiedon hyödyntäjiä.
Teknisen dokumentaation rakenne
Palvelukorttiin linkitetään palvelun tekninen dokumentaatio, jossa pitää löytyä ainakin seuraavat osa-alueet:
- Arkkitehtuuri
- Käytetyt teknologiat
- Sisäiset ja ulkoiset integraatiot
- kuvaus palvelun rajapinnoista
Palvelukortti | |
|---|---|
| Palvelun nimi | Esim. valtionavustusjärjestelmä |
| Palvelun kuvaus | |
| Palvelun omistaja | Palvelun omistava yksikkö |
| Palvelun kohderyhmä | Esimerkiksi kansalaiset, koulutuksen järjestäjät tai muut viranomaiset. |
| Toiminnallisuudet | Tässä kuvataan, miten sovelluksen pitäisi toimia. Makron avulla saa listalle käyttötapauksien otsikkotason linkkeinä. |
| Palvelun tyyppi | substanssipalvelu / yleiskäyttöinen palvelu. |
| Käyttöohjeet | Linkki käyttöohjeisiin |
| Prosessikuvaukset | Kuva (tai linkki QPR-kuvaukseen (Tähän tulossa ohje QPR:n hyödyntämisestä)) |
| Tietomalli | Linkki QPR:ssä tehtyyn tietomalliin tai kuva (Tähän tulossa ohje, miten linkitys tehdään) |
| Käsitteet | Tähän linkki OKSA-sanastoon tai listaus käytetyistä käsitteistä (esim. näyttötodistus, näyttötutkintotodistus) Linkitys tehdään kohdasta hakemisto. |
| Tekninen dokumentaatio | Linkki tekniseen dokumentaatioon |
| Rajapinnat | Linkit rajapintoihin ja rajapinnan käyttöohjeisiin, esim: Rajapintojen kutsuesimerkkejä |
| Tietokantakuvaukset | Tietokantakuvaukset generoituvat automaattisesti (SQL Fairy) CI-palvelimella master branch buildin yhteydessä. |
| Versioitu lähdekoodi | |
| Tietoturva | linkki dokumentaatioon |
| Kehitysnäkymä | |
| Julkaisutiedot (release notes) | Linkki tikettijärjestelmään |
| Raportoidut virheet (bugit) | Linkki jiraan (esim. Opintopolku bugit) |
| Linkit palveluun | Linkit sellaisiin ympäristöihin, joihin pääsee internetistä. |
| Lisensiointi | Opetushallituksen käyttämä EUPL-lisenssi |
Yhteyshenkilö | Nimi ja sähköposti |