Overingeniør, Institutt for Informatikk
| Printer friendly format for http://doc.uib.no/wiki/DocSkriving : | Display with child pages or without header |
DocSkriving |
Denne informasjonen er skrevet for folk som har lov til å lage dokumentasjon under Dokumentasjonsprosjektet.
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.
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
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.
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 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.
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 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] .
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