Tyyliohjeita

Yleisrakenteesta

WWW-dokumenttia kirjoitettaessa teksti kannattaa jakaa useisiin tiedostoihin jonkin loogisen rakenteen, esimerkiksi luku- tai kappalejaon, mukaan. Mitä pienempiin yksiköihin teksti jaetaan, sitä helpompaa on tehdä assosiaatiomaisia alaviitteitä ja reunahuomautuksia, mutta sitä vaikeampaa on tehdä dokumentista helppolukuinen ja selkeärakenteinen.

Kohderyhmä pitää ottaa huomioon dokumenttirakennetta suunniteltaessa: jos teksti on suunniteltu aloittelijoille, kannattaa käyttää yksinkertaista ja selkeää hierarkkista puurakennetta, jossa eri luvut ja kappaleet on siististi sijoiteltu niin, että dokumentin voi lukea tavallisen kirjan tapaan. Luonnollisesti, mikäli käsiteltävässä asiassa erottuu selkeä rakenne, minkä oppimisesta on hyötyä, kannattaa dokumentti jaotella sen mukaan.

Asiantuntijoille tarkoitettu teksti voi sisältää enemmän viitteitä lukujen välillä, teknisiin määrittelyihin tai jopa dokumentin ulkopuolelle. Asiaan perehtyneet ihmiset ovat jo mielessään luoneet jonkinlaisen kuvan asioiden paikoista ja niitten suhteista toisiinsa, ja tätä kannattaa käyttää hyödyksi myös dokumentin rakenteessa.

Dokumentin jako tiedostoihin kannattaa tehdä siten, että voi tarvittaessa luoda kaksi tai useampia hakemistoa eri kohderyhmille.

Dokumentin rakennetta selkeyttää, mikäli sillä on selvästi erottuva "etusivu". Tälle sivulle voi ison, selvästi erottuvan otsikon, sisällysluettelon ja esittelyn lisäksi sijoittaa tietoa dokumentin virallisuudesta, ajankohtaisuudesta jne.

Yksittäiset tiedostot

Jokaiseen tiedostoon kannattaa laittaa linkki, joka viittaa tietoihin tekijästä. Tämä mahdollistaa vaivattoman palautteen antamisen. Useasti päivitettäviin tiedostoihin on syytä merkitä kirjoituspäivämäärä, ja jonkinlainen status ("epävirallinen luonnos hilavitkutinprojektin aikataulusta") saattaa olla paikallaan, mikäli etusivulla ilmoitettu ei sovi.

Varmaankin jokaisessa lukuohjelmassa voidaan peruuttaa kuljettua polkua pitkin linkki kerrallaan, mutta "pikavalinnat" ylemmälle/ylimmälle hierarkkiselle tasolle nopeuttavat lukemista ja vähentävät lukijan turhautumista.

Kontekstivapaus

Julkisesti luettaviin dokumentteihin kuka tahansa saattaa tehdä linkkejä mistä tahansa. Tästä syystä kannattaa kirjoittaa niin, että teksti ei ole tiukasti sidottu tiettyyn esitysjärjestykseen, vaan pitäisi pyrkiä rakentamaan palikka, jota modulaarisen ohjelmoinnin periaatteita noudattaen voisi käyttää muissakin yhteyksissä. Käyttämällä lauseita kuten "Edellisen luvun ongelman esittelyn jälkeen tarkastelemme..." romutetaan "portattavuus" helposti.

Perustermien selityksiä varten kannattaa joka tiedostoon laittaa yksi linkki per termi, ettei jostain muualta keskelle dokumenttia hyppäävä ole aivan eksyksissä.

Otsikkojen kanssa on syytä olla tarkkana: esimerkiksi <TITLE>Ongelman kuvaus</TITLE> ei kerro yhtään mitään henkilölle, joka ei ole seurannut määrättyä reittiä.

Laiteriippumattomuus

Dokumenttia ei saa missään tapauksessa muotoilla sen mukaan, miltä se näyttää omalla ruudulla. Ylimääräiset rivinvaihdot otsikoitten tai kappaleitten jälkeen saattavat näyttää huonoilta jossakin ohjelmassa siinä missä ne näyttävät hyvältä toisessa, eikä kirjaisintyyleihin tai -kokoihin saa luottaa. HTML-dokumentin ulkoasua ei yksinkertaisesti voi muotoilla pilkun tarkkuudella kuin juuri sille laitteisto- ja ohjelmakokoonpanolle, mitä satut käyttämään.

Laiteriippumattomuuteen voisi lukea myös sen, että dokumentin tulisi näyttää hyvältä paperille tulostettuna. Valitettavasti hyperlinkit siirtyvät huonosti paperille, eikä esimerkiksi jokaisen tiedoston allekirjoitus-linkki näytä hyvältä.

Luettavuus

Vältä muotoa "ohjeita näppäimistön puhdistamiseksi napanöyhdästä täällä". Tätä ns. here-syndroomaa kohtaa valitettavan usein yhdysvaltalaisissa dokumenteissa.

Sitä, että linkit ovat linkkejä, ei tarvitse mainita. Ei siis "Linkki lisp-tulkin lähdekoodiin" vaan yksinkertaisesti "lisp-tulkin lähdekoodi".

Tekniikasta asioitten takana ei muutenkaan kannata turhaan puhua, etenkin jos dokumentti on tarkoitettu sellaisten ihmisten luettavaksi, jotka eivät ole alan ammattilaisia. "Julkisohjelma-arkistomme tarjoaa grafiikkasovelluksia Macille" on parempi kuin "Macin grafiikkaohjelmia sisältävä FTP-palvelimemme on tavoitettavissa WWW:stä".