Toivoisin (= toivonut jo pari kymmentä vuotta), että joidenkin ohjelmien ohjeiden tyyliä harkittaisiin tarkemmin.
- (MIKÄ) Ohjeen alkuun kuuluu lyhyt selitys siitä, mikä jokin on ja mihin se on tarkoitettu
- (Milloin) Paketissa olevan ohjelman versio ja päivämäärä
- (Miksi) maininta, minkä aiemman ohjelman tilalle tämä versio on tehty ja miksi
- (Miten) selitys siitä, miten sitä käytetään
- parametrit
- (Miksei) mahdolliset ongelmat ja rajoitukset
- (Contributions to) Loppupuolelle ohjeen laatija voisi kirjata kuvauksen omasta osuudestaan sekä kiitokset asiaan osasllistuneille.
- (version list) Aivan loppuun voi lisätä listauksen muutoksista, joita järjestelmään on vuosien kuluessa tehty. Tämän listan olemassaolo kertoo käyttäjälle, että ohjelma ei vieläkään ole julkaisukelpoinen ja että sen jatkokehittelystä on luovuttu.
Harmittavan usein verkosta löytyy keskustelupalstoilla ketjuja, joissa selvästi kysyjän ongelma ratkeaisi hetkessä, jos ohjelman MAN-sivu olisi laadittu 'human readable' muodossa. Monesti näissä vielä vastaukset on laadittu sanoja säästellen ja näennäishumoristisessa muodossa, jolloin vastaus sinänsä aiheuttaa lisää työtä ja turhautumia kysyjälle. Aivan kuin vakuutusyhtiön konttorissa, jossa ei saa selvää vastausta vaikka kysyisi kellonaikaa.
Aivan liian usein näkee ohjeita, joista ei edes selviä, mihin jokin ohjelma on tarkoitettu.
Samoin ohjelman asennusohjelman pitäisi antaa edes lyhyt luonnehdinta siitä, mihin ohjelma on tarkoitettu.
Parametrien listaus on monesti kirjoitettu kuin olettaen, että käyttäjä luonnostaan tietää, mitä milläkin parametrilla tekee ja mitä arvoja jokin parametri hyväksyy ja vielä senkin, mikä on komennon syntaksi.
Monista ohjeista paistaa läpi, että alkuperäinen (Amerikkalainen) ohjeteksti on laadittu kirjaa varten, missä kustantaja maksaa painettujen sanojen lukumäärän mukaan. Kertomukset hauskoista sattumuksista ja naapurin koiran ruokatavoista eivät edes kevennä tekstiä.
Onneksi Linuxista on (suurelta osin) jäänyt pois Windowsia vaivaava tyyli, missä tavoitellaan teennäisen teknistä sävyä sivistyssanoilla ja lausekäännöksillä:
'Ethän halua kieltää toiminnon estävän rajoituksen hyväksymättä jättämistä [Enable/Disable]'
Tämä kommenttini aktulisoitui yritettyäni löytää ohjetta SFTP:n siirtologin aktivoimiseksi ja jatkui, kun koitin löytää selvitystä, mikä LVM on ja mitä se tekee ja miten.
Jos tietää (kuten minä) että oma teksti on kaukana kaunokirjallisuudesta, voi pyytää jotain paremmin kynänsä hallitsevaa auttamaan.
