Retningslinjer for dokumentasjonsskriving

Denne informasjonen er skrevet for folk som har lov til å lage dokumentasjon under Dokumentasjonsprosjektet.

Hva er ZWiki?

Zwiki er en måte å samle og organisere informasjon. De har en helt unik syntaks og bruk som gjør det meget enkelt å lage dokumentasjon.

Når jeg prøver å redigere blir jeg spurt etter konto?

Det er åpent for hvem som helst til å redigere våre sider.

Merk at for å logge inn må du bruke følgende:

Login:   dokumentasjon
Passord: dokumentasjon

Hvem er vår målgruppe?

Når vi først begynner Dokumentasjonsprosjektet, så kan vi like godt prøve å skrive for for et bredest mulig publikum. Men selvsagt skal først og fremst brukere fra MNFA være av prioritet.

Dokumentasjonsskriving

Dokumentasjonen bør skrives på Norsk, og bør helst være generell. Prøv å ikke nevne versjonsnavn og årstall som kan forvirre leseren, når man allikevel vet at det aktuelle objekt ikke kommer til å forandre seg i noen særlig grad. Om man vet at programmet eksisterer på flere operativsystem, bør man ikke nevne operativsystemavhengige kommandoer før i et slags vedlegg til slutt (eventuelt et separat dokument). F.eks. MatLab er meget likt på de ulike platformer, og dermed skal man unngå å nevne hvor man finner programmet på startmenyen i Windows. Unngå også eventuelle kritikker eller diskusjoner. Prøv å være objektiv, og sett deg inn i brukerens situasjon. Prøv å utfylle med linker til andre objekter som kan være av interesse.

Zwiki tekstformatering

Zwiki fungerer slik at den gjenkjenner et ord som inneholder klammeparentes [ og ]? rundt alle ord som skal linkes videre. F.eks. [DetteSkalLinkes]. Etter at en har lagret et ord med klammeparentes rundt vil man automatisk få opp et [DetteSkalLinkes]? <- spørsmålstegn etter klammene. Da kan man trykke på spørsmålstegnet og lage dette dokumentet.

Generelt

Et utropstegn (!) forann klammeordet vil fortelle Zwiki at dette ikke er noen link. f.eks. ![IkkeLink]
Et stjernetegn (*) rundt ordet vil gi et ord i kursiv.
Du kan skrive vanlig HTML kode, men unngå de mest fancy.
- Alle overskrifter skal ta bruk av <h1> Største overskrift </h1> og nivåer ned til h3 for de minste overskriftene.
Zwiki er en implementasjon av WikiWikiWeb , og støtter derfor det meste av http://www.c2.com/cgi/wiki?TextFormattingRules
Zwiki krever ofte at en har litt ekstra linjeskift slik at den kan lokalisere at du faktisk vil ha ny linje. Så bruk linjeskift flittig.

Bildebruk og opplast av filer

Zwiki støtter at en kan laste opp bilder og filer. Dette blir forbundet med et dokument, og man kan, om man har rettigheter, få opp en Attach file/image - meny nederst om man redigerer en side. Her er det da bare å laste opp et bilde eller en fil.

Merk at bilder bør være i formatet gif om man har enkel grafikk fra vanlige programmer, men man kan selvsagt også bruke jpeg. Man skal ikke bruke skyggelegging eller andre fancy filtre som eventuelt ditt program kan støtte. Bildene bør ikke være for store.

Andre språk

Andre språk skriver vi som (kursiv inne i en parentes). Man må gjerne skrive informasjon på engelsk om man mestrer dette bra. Hvis det er mange som etterspør en viss dokumentasjon på engelsk, kan man lage en egen versjon av dokumentet til [LenkeNavn_en] .

Forhindring av spam

For å forhindre at noen motorer henter inn epostadresser fra Dokumentasjonsprosjektet, skal man ikke skrive ut emailadresser rett ut. Bruk gjerne {at} eller lignende for å forhindre alfakrøll bruk. f.eks. ola.nordmann {at} uib.no

Oktober 2003,

Hallstein Lohne

Overingeniør, Institutt for Informatikk