Helsingin yliopisto > Tietojenkäsittelytieteen laitos > Ohjelmointitekniikka (Java) -opintojakso keväällä 2005
Tämän tekstin ensisijainen tarkoitus on auttaa sinua kirjoittamaan Ohjelmointitekniikka-kurssilla parempia artikkeleita tietoteknisistä aiheista. Lue tämä teksti
Tämän tekstin toissijainen tarkoitus on perustella artikkelistasi annettuja pisteitä. Vertaa tekstissä annettuja neuvoja omaan arvosteltuun artikkeliisi. Löytämäsi ansiot ja puutteet muodostavat merkittävän osan saamiesi pisteiden perusteluista. Tämä teksti on kirjoitettu yleisluontoiseksi, joten aihekohtaisia sisällöllisiä virheitä tai puutteita tässä tekstissä ei olla käsitelty.
Aseta artikkelillesi tavoite. Päätä mitä artikkelin lukijoiden pitäisi tietää tai osata artikkelin luettuaan tai artikkelin avulla. Et voi arvioida artikkelisi hyvyyttä ellei artikkelillasi ole tavoitetta, aivan kuten et voi arvioida ohjelman hyvyyttä ellet tiedä mitä ohjelmalla pitäisi saada aikaan. "Ratkaisu harjoitustehtävään" ei ole kunnollinen tavoite. Artikkelisi tulee olla itsenäinen kokonaisuus, joka on käyttökelpoinen, vaikkei lukija tietäisi harjoitustehtävää. (Toki artikkelin täytyy silti soveltua harjoitustehtävän ratkaisuksi.)
Suhteuta artikkelin tavoite ja laajuus kurssilta saataviin opintoviikkoihin. Tällä kurssilla kunkin opiskelijan oletetaan työskentelevän kurssin parissa vajaat 30 tuntia kaksiviikkoisjakson aikana. Tämä tuntimäärä sisältää kaiken kurssiin liittyvän työn eli artikkelin kirjoittamisen lisäksi myös luennot, ryhmätapaamiset, lähdemateriaaliin tutustumisen ja niin edelleen.
Sijoita artikkelin alkuun lyhyt kuvaus artikkelin aiheesta. Lukijan pitäisi artikkelin alun luettuaan pystyä arvioimaan kiinnostaako artikkeli häntä. Joskus voi olla hyvä idea todeta artikkelin tavoite eksplisiittisesti artikkelin alussa.
Kirjoita kohdeyleisöllesi. Kun pidät mielessä artikkelisi kohdeyleisön, voit arvioida mitä lukijoiden voidaan olettaa tietävän ja mitä ei. Tällä kurssilla kirjoitettavien artikkelien kohdeyleisöksi ajatellaan lukijat, joilla on samat esitiedot kuin tämän kurssin osallistujilla eli Java-ohjelmointi-, Tietorakenteet- ja Rinnakkaisohjelmistot-kurssit.
Jäsentele artikkelisi pieniksi kokonaisuuksiksi, joissa jokaisessa käsittelet jonkin tietyn aiheen.
Suoraan harjoitustehtävä pilkkomalla aikaansaatu jäsentely ei yleensä toimi. Jos esimerkiksi tehtävä sisältää kysymyksen "Parantaako väittämien käyttö ohjelmistojen laatua?", artikkeliin tuskin kuitenkaan kannattaa laittaa väliotsikkoa "Parantaako väittämien käyttö ohjelmistojen laatua". Yleensä tällainen menettely on osoitus pyrkimyksestä alittaa aita sieltä mistä se on matalin.
Selosta kaikki käsitteet, jotka eivät kuulu lukijoiden oletettuihin esitietoihin. Jos et ole varma, voidaanko jotakin olettaa tiedetyksi, kallistu mielummin selittämisen kuin selittämättä jättämisen suuntaan.
Jos vain suinkin mahdollista, järjestele kokonaisuudet sellaiseen järjestykseen, että artikkelissa ei käytetä uusia käsitteitä ennen kuin ne on selostettu. Esimerkiksi For-Each-toistolausetta ei ole järkevää käyttää koodiesimerkeissä ennen kuin kyseinen toistolause on esitelty.
Otsikoi koko artikkelisi pääotsikolla. Otsikoi artikkelisi sisältämät pienet kokonaisuudet väliotsikoilla. Laajassa artikkelissa saattaa olla syytä käyttää hierarkkista otsikointia. Otsikot
Usein kannattaa laatia väliotsikoiden perusteella artikkelin alkuun pieni sisällysluettelo artikkelinsisäisine linkkeinen.
Otsikon ja otsikoidun tekstin pitää olla sopusoinnussa keskenään. Jos otsikko on vaikkapa "Väittämien käyttökohteet", ei tuon otsikon alla pidä yhtäkkiä kirjoittaa väittämien kytkemisestä päälle tai pois päältä. "Lopuksi", "Muuta" ynnä muut vastaavat eivät kerro otsikoimastaan tekstistä mitään, joten ne eivät ole hyviä otsikoita.
Käytä artikkelissasi suomenkielisiä käsitteitä. Artikkelisi yksi suurimmista anneista on nimenomaan se, että artikkeli on kirjoitettu lukijansa äidinkielellä. Assert on väittämä, block on lohko, wrapper on kääreluokka, cast on tyyppimuunnos ja niin edelleen. Liitä käsitteiden ensimmäisen käyttökerran yhteyteen myös niiden englanninkielinen versio.
Älä sekoita suomea ja englantia. Esimerkki: älä kirjoita "castaa objecti Integeriksi" vaan "muunna olio Integer-tyyppiseksi".
Vältä suoraa lainaamista. Jos lainaat tekstiä suoraan - kääntäen tai kääntämättä - sinun on merkittävä teksti lainausmerkkeihin ja merkittävä lähde lainan yhteyteen. Lainaamista kannattaa käyttää lähinnä silloin, kun joku kirjoittaja on ilmaissut jonkin asian äärimmäisen osuvasti, kirkkaasti tai oivaltavasti.
Perehdy eri lähteisiin, selvitä itsellesi mistä oikein on kysymys ja ilmaise se sitten omin sanoin. Lähes suoraan lähteestä käännetty teksti on melkein poikkeuksetta kömpelöä. Varsinkin jos et oikein ymmärrä jotakin asiaa, älä yritä kiertää ongelmaa kääntämällä lähdetekstiä sana kerrallaan. Lukija kyllä huomaa, että kirjoitat asiasta, jota et ymmärrä. Myös suoranaisten asiavirheiden riski on tällöin suuri.
Kirjoita täsmällisesti. Esimerkiksi muuttuja on eri asia kuin muuttujan arvo: arvon palauttava metodi ei koskaan palauta muuttujia eikä Vector-tyyppiseen olioon voi tallentaa muuttujia.
Päätä mitä sanaa käytät mistäkin käsitteestä ja käytä sanaa johdonmukaisesti. Älä esimerkiksi puhu välillä metodeista ja välillä operaatioista, jos kuitenkin tarkoitat yhtä ja samaa käsitettä.
Näytä, älä vain selitä. On pöhköä esimerkiksi kuvailla poikkeuksiin liittyvää luokkahierarkiaa pelkästään sanallisesti, kun hierarkian piirtäminen välittää saman tiedon paljon helpommin. Monille ihmisille kuvat myös jäävät helpommin mieleen.
Pyydä jotakuta ulkopuolista henkilöä lukemaan tekstisi ja kertomaan heti, jos hän ei saman tien ymmärrä jotakin kohtaa. Kirjoita uusiksi jokainen kohta, jota lukija ei ymmärtänyt. Voisi olla hyvä idea, että sovitte kullekin aiheelle opintopiiriläisten joukosta "tekstineitsyt", joka tutustuu aiheeseen ensimmäistä kertaa jonkun toisen kirjoittaman artikkelin perusteella.
Verkkosivuilla ei kannata käyttää tehokeinona alleviivausta, sillä alleviivattuja sanoja luullaan helposti linkeiksi.
Pidä koodiesimerkit yksinkertaisina, mutta tee niistä silti
todentuntuisia. Vältä int foo = bar() -tyyppisiä esimerkkejä:
tee esimerkit sellaisiksi, että lukija voisi kuvitella niiden olevan poimittu
todellisesta ohjelmasta.
Selosta mitä koodiesimerkissä tapahtuu: älä jätä lukijan vastuulle selvittää mitä koodi oikein tekee.
Jos koodi tulostaa jotakin tai aiheuttaa poikkeuksen, on useimmiten järkevää näyttää esimerkki tulostuksesta tai virheilmoituksesta.
Kirjoita tekstin joukkoon vain selitettävän asian kannalta keskeisimmät koodin osat. Linkitä tekstin yhteyteen kokonainen, suorituskelpoinen koodi, jonka lukija voi kopioida, kääntää ja suorittaa.
Tarkista kaikki koodiesimerkit kääntämällä ja suorittamalla ne. Siis ihan oikeasti. Harva asia on yhtä noloa kuin ohjelmoinnista kertova artikkeli, jonka koodiesimerkit sisältävät ohjelmointivirheitä.
Merkitse virheellinen tai huonoa tyyliä edustava koodi selvästi.
© 2005 Joni Salmi. Tämän oppimateriaalin käyttö on sallittu vain yksityishenkilöille opiskelutarkoituksissa. Materiaalin käyttö muihin tarkoituksiin, kuten kaupallisilla tai muilla kursseilla, on kielletty.