Kirjoittelen Vuorovaikutukseen toisinaan myös vapaamuotoisia kolumneja, mutta ylivoimaisesti suurin osa blogin merkinnöistä on ongelmien ja niiden ratkaisujen kuvailuja. Seuraavassa kuvailen näiden ongelma-aiheisten merkintöjen rakennetta.

---

Ongelma-aiheisen merkinnän otsikko on tiivis kuvaus ongelmasta. Kun olen ratkaissut ongelman, merkitsen sen kirjoittamalla otsikon alkuun [Ratkaisu].

Merkinnän sisällössä, lauseiden sisällä korostan sovellusten ja pakettien nimet, komentoriviltä annettavat komennot ja muut näytöllä näkyvät termit tai nimitykset (esimerkiksi Sovellukset-valikko) muusta tekstistä poikkeavalla kirjasinlajilla ja kirjasimen värillä silloin, kun ne esiintyvät merkinnässä ensimmäistä kertaa. Ensimmäisen maininnan jälkeen en korosta nimityksiä enää saman merkinnän sisällä.

Kun sisällytän koodilistauksia merkintöihin, panen niistä suoraan ladattavat kopiot tiedostot-hakemistoon ja linkitän kopiot listauksien alle aina siinä tapauksessa, että listaukset toimivat periaatteessa sellaisenaan, ilman että niihin täytyisi tehdä käyttäjä- ja konekohtaisia muutoksia. Mikäli muutoksia vaaditaan, en anna listauksesta valmista kopiota. Silloin koodi täytyy kopioida tekstieditorin kautta tiedostoon, ja sen pitäisi toimia muistutuksena siitä, että tiedostoon täytyy tehdä editorissa sovelluksia (esimerkiksi hakemistopolkuja täytyy muuttaa) ennen kuin se voi toimia.

Sisältö jakautuu kolmesta viiteen eri osioon. Seuraavassa kuvailen kunkin osion alle täyttämieni tietojen tavoitteita. Käytännössä osioiden sisällöt saattavat poiketa tässä kuvaamistani tavoitteista, mutta silloin kyse on yleensä omasta huolimattomuudestani.

Lähtökohta

Kuvaus ongelmankuvauksen kannalta keskeisistä asetuksista, käytetyistä ohjelmista ja mahdollisista muista tekijöistä. En kuitenkaan merkise lähtökohtiin UNIX-järjestelmissä tyypillisesti aina asennettuina olevia apuohjelmia kuten sed, grep, wget ja niin edelleen.

En myöskään merkitse ohjelmien versionumeroita, koska en tutki ongelmia niin tarkkaan että voisin varmuudella sanoa niiden olevan versiokohtaisia. Ne voivat olla sitä, mutta tänne jonkin ongelman ratkaisua etsiessään saapuva toinen käyttäjä saattaa siitä huolimatta hyötyä tarjoamastani ratkaisuehdotuksesta. Tästä säännöstä saatan poiketa Linux-ytimeen mahdollisesti liittyvien ongelmien yhteydessä.

Ongelma

Ongelman ydin: mitä tapahtuu ja mitä odotin sen sijaan tapahtuvaksi tai mitä pitäisi sen sijaan tapahtua. Toisinaan taas lyhyemmin: mitä en tiedä tai osaa tehdä.

Ongelman syy

Mikä on ongelman välittömin aiheuttaja. Tavoitteeni syyn kuvailussa on pragmaattinen; jos vaikkapa jokin asetus on pielessä, en Ongelman syy -otsikon alla pohdi sitä miksi se on pielessä, vaan tyydyn vain asian toteamiseen. Yleisesti ottaen päämääräni ei tässä blogissa ole filosofoida vaan esitellä kulloinkin käsillä olevan ongelman ratkaisuja olennaisilta osiltaan.

Toisinaan ongelmalle ei ole mitään mielekästä syytä. Näin on varsinkin silloin, kun ongelmassa on kyse suoraviivaisesti tiedon puuteesta. Tällöin jätän ongelman syy -osion otsikoineen kokonaan pois.

Ratkaisu

Mitä tein yllä kuvatun ongelman ratkaistakseni.

Huomautus/Huomautuksia

Muuta ongelmaan liittyvää tietoa, kuten ratkaisun löytöpaikka sikäli kun sen maininta ei ole soveltunut muiden, yllä olevien otsikoiden alle. Jos huomautettavaa ei ole, jätän tämän osion otsikoineen merkinnästä kokonaan pois.

Kunkin merkinnän, kuten näiden, varsinaisen sisällön ulkopuolella olevien artikkeleidenkin perään voit halutessasi jättää kommentteja aiheesta. Mikäli sinulla on oma blogi ja sen pohjalla oleva ohjelmisto tukee TrackBack-protokollaa (niin kuin esimerkiksi WordPress tekee), aiheiden kommentointi onnistuu myös siten, että kirjoitat omaan blogiisi merkinnän, jossa linkität Vuorovaikutuksessa olevaan merkintään. Silloin täällä olevan merkinnän kommenttiosioon pitäisi pian ilmestyä paluuviite sinun blogissasi olevaan merkintään.

Pyrin käyttämään kommenttiosiota myös siihen liittyvässä tekstissä tapahtuvien merkittävien päivitysten ylöskirjaamiseen. Kirjaan muistiin esimerkiksi ratkaisun löytymisen aiemmin ratkaisua vailla olleeseen ongelmaan. Siten kommenttiosio toimii samalla myös tekstin muutoshistoriana, ja jos jonkin ongelman ratkaisun etsiminen kiinnostaa sinua, voit tilata merkinnän kommentit sen perässä pientä pränttiä sisältävän tietolaatikon sisältämän RSS 2.0 -linkin kautta.

Vuorovaikuttaja julkaisi tämän artikkelin torstaina 7. helmikuuta 2008 kello 16:31. Merkintä kuuluu luokkiin sekalaiset. Artikkelista käytävää keskustelua voit seurata RSS 2.0 -syötteen avulla. Voit jättää kommentin tai viitata artikkeliin omalla sivustollasi.