Raportin kirjoittaminen

Millainen raportti pitäsi kirjoittaa, kun testaa jotakin tietokoneella? Nämä ohjeet on kirjoitettu Linux-kurssieni harjoitustehtäviä silmällä pitäen, mutta ne soveltuvat minkä tahansa tietokoneiden teknisten testien raportointiin. Näitä ohjeita on toivottu monesti.

Raportointi tarkoittaa, että kerrot täsmällisesti mitä teit, ja mitä sitten tapahtui. Kirjoita raporttia koko ajan samalla kun teet. Helpointa on kirjoittaa raportit suoraan sähköiseen muotoon.

Kirjoitan yleensä muistiinpanot jo itseänikin varten, kun tutkin jotain teknistä ongelmaa. Aikaa säästyy, kun ei tarvitse turhaan toistaa vaivalloisia koejärjestelyjä. Myös ajatukset selkenevät, kun kirjoittaa jäsenneltyjä muistiinpanoja. Raportteja voi käyttää pohjana, kun laatii toisille ohjeistoja järjestelmien toteutukseen ja ylläpitoon.

• Jos annan rapotin toiselle opiskelijalle samassa ympäristössä, pitää tulla sama tulos kaikkine harhapolkuineen
• Raportoi myös ympäristö. Moni asia toimii eri tavalla, jos käyttää eri tietokonetta eri verkossa. Esimerkiksi: “Tein harjoituksen perjantaina 2006-05-19 Helia-talon tietokonelaboratoriossa h5013. Koneena oli Dell GX270 työasema, monitorin jalassa oli numero 17. “.

• Minkä komennon annoit tai mitä klikkasit?
• Kellonajat. Samalla selviää, miten paljon eri työvaiheisiin menee aikaa. Aikoja vertaamalla voi jälkeenpäin päätellä, onko jokin vika ollut koko verkon laajuinen.
• Onnistuiko? Mitä toimenpiteen jälkeen tapahtui? Jos jokin tehtävä onnistui tai epäonnistui, millä testillä totesit tämän? Esimerkiksi vikailmoitus “tietokone ei toimi” on aika lailla hyödytön.
• Onko työkaluissa (Ubuntussa, IDEssä...) vikaa? Raportoi odottamattomat tulokset. Lähetän toistettavat virheraportit mahdollisuuksien mukaan ohjelmien tekijöille. Ehkä vika on korjattu, kun tarvitset ohjelmaa töissä.
• Onko labrassa tai koneissa vikaa? Lähetä täsmällinen vikailmoitus suoraan osoitteeseen juhani.ahlgren palvelimella helia.fi. Käytännössä vikoja korjataan ainoastaan ilmoitusten perusteella.
• Kirjoita menneessä aikamuodossa eli imperfektissä: “valitsin ‘tyhjennä’“, “irroitin johdon”, “laitteesta alkoi nousta savua”.

• Käytä väliotsikoita
• Kirjoita huolellista kieltä. Luottasitko sellaseen hammasläkäriin, jonka wepisilvulla hirveesti on kirjotusvirhietä?
• Kirjoita kanavaan sopivasti. Weppisivulla ei tarvitse noudattaa Helian paperijulkaisuihin tarkoitettuja ohjeita.
• Jos haluat, voit kirjoittaa lopuksi yhden kappaleen tiivistelmän raportin alkuun “Asensin onnistuneesti Apache-weppipalvelimen ja käyttäjille mahdollisuuden tehdä kotisivuja. Kuvailen myös epäonnistuneen yrityksen asentaa PHP-skriptien tuki.”

• Hyvä tapa ja akateeminen käytäntö vaatii viittauksia. Viittaukset osoittavat myös, että kirjoittaja on perehtynyt alueeseen.
• Esimerkkejä:
  • Koistinen, Maija 2003: Apachen asennus, harjoitus 3. Kotitehtäväraportti. http://myy.helia.fi/~a123/linux/h-3.html
  • Teittinen, Urpo 2006-03-27. Suullinen tiedonanto.
  • Mynttinen ym. 1997: Practical Infection Vectors for Production Servers.
  • Karvinen, Tero: Oppitunnit 2006-05-18, Linux tutustuminen -kurssi (www.iki.fi/karvinen/linux_tutustuminen.html).

• “Tätä dokumenttia saa kopioida ja muokata GNU General Public License (versio 2 tai uudempi) mukaisesti. http://www.gnu.org/licenses/gpl.html”
• “Pohjana Tero Karvisen Linux-kurssi, www.iki.fi/karvinen”

Lisenssin valinta on vapaaehtoista, mutta GPL on suositeltava lisenssi.

• Sepittäminen. Ei saa väittää, että olisi tehnyt testejä, joita ei ole oikeasti tehnyt. Vain tehtyjä töitä saa raportoida. Kun sepitteissä tapahtuneita asioita yritetään turhaan toistaa, tuhrautuu rutkasti aikaa. (Sepittäminen on rangaistavaa vilppiä)
• Plagiointi. Tekstin kopioiminen lähdettä ilmoittamatta tai toisten tulosten esittäminen ominaan. (Plagiointi on rangaistavaa vilppiä. Luvaton kopiointi loukkaa tekijänoikeuksia)
• Kuvien luvaton kopiointi wepistä osaksi työtä. (Plagiointi on vilppiä. Luvaton kopiointi loukkaa tekijänoikeuksia).

Verkossa on myös paljon kuvia, joita saa yhdistää omiin töihin. Lähde on aina ilmoitettava. Kotitehtävissä työn tulee olla pääosin opiskelijan itse tekemä.