Retningslinjer og tips til skriving

Strukturering av tekst

Når en leser en wiki-side, så er det umulig å vite hva en har lest fra før og hvor en kommer fra. Derfor er det viktig å sette det en skriver inn i en sammenheng. Dette kan gjøres ved å tredele teksten:

1. Først kommer en innledning, typisk ett avsnitt hvor en har en myk introduksjon som refererer til begreper/sider som det er naturlig å ha lest.
2. Så kommer teksten om temaet, som gjerne kan lenke til andre begreper/sider.
3. Til slutt kommer en oppsummering/avrunding som refererer til hva det er naturlig å lese etterpå.

En av fordelene med denne tredelingen er at en naturlig får lenket til andre sider og ikke gjør seg avhengig av blokken med lenker som Confluence automatisk legger inn i web-versjonen. Denne blokken er ikke med i mobil/tablet-versjonen, så derfor er det bedre å ha eksplisitt lenker.

Metadata for sider

Metadata er data som er knyttet til en side og som ikke oppfattes som en del av (det tematiske) innholdet i side. Metadata kan brukes til søk og oversiktstabeller og kan være nyttig både for de som konsumerer og produserer innhold.

Confluence lar en knytte nøkkelord og nøkkel/verdi-par til en side med henholdsvis labels-feltet og metadata-list-makroen. Nøkkelord (altså labels) kan brukes med Browse->Labels-funksjonen for rask navigering til alle sider med et bestemt nøkkelord. Men kanskje mer viktig er at en kan filtrere på nøkkelord ved generering av tabeller med metadata-report-makroen og beregning av verdier med metadata-calculate- og metadata-matches-makroene. Nøkkel/verdi-parene kan vises i tabeller, men ikke filtreres på. De kan dessuten brukes i grafer og diagrammer med chart-macroen. Muligheten som disse makroene gir, er i stor grad bakgrunnen for hvordan vi velger å legge inn metadata med labels- og metadata-list-mekanismene.

Sidetype: Dette er en grovkategorisering av en side etter hva slags type innhold den har og legges inn både som en label med sidetype- som prefiks (f.eks. sidetype-oversikt) og som metadata. Vi har (foreløpig) identifiser følgende kategorier:

• oversikt - introduserer et tema og forteller hvordan undersider dekker det
• teori - forklarer et tema
• eksempel - viser hvordan en løser et problem, typisk kodingsproblem
• oppgave - ulike typer øvelser eller oppgaver

Siden sidetype primært brukes til filtrering, så er det bare viktig å legge inn dette på sider som en ønsker å vise i spesialiserte tabeller.

Ferdig(stillelsesgrad): Hvor ferdig en anser seg for å være med siden. Vi velger å bruke en prosent-skala, men begrenser oss til verdiene 0, 25, 50, 75, 95 og 100. Her er 95 tenkt å angi at en anser seg som ferdig, men trenger et godkjenningsstempel fra fellesskapet. Vanligvis vil verdien øke etterhvert som en jobber med siden, men verdien kan også settes ned, f.eks. dersom kommentarer (klager) viser at innholdet bør revideres.

Dekningsgrad: Angir (grovt sett) i hvilken grad (relevante aspekter av) et tema er dekket. Dersom man har lest og forstått en side med full dekningsgrad, så skal man i prinsippet ikke trenge å lese annet materiale. Vi velger å bruke en prosent-skala, men begrenser oss til verdiene 0, 25, 50, 75 og 100.

Omfang: Angir (grovt sett) hvor grundig et tema er behandlet. Dersom et tema er grundig behandlet så skal en ikke trenge å øve mer på det for å få det til å sitte. Vi velger å bruke en prosent-skala, men begrenser oss til verdiene 0, 25, 50, 75 og 100.

Dekningsgrad og omfang skal gi veiledning til leseren om hvor stort læringsutbytte en side er ment å gi.

Oppgaver

Hver side/tema bør ha (inneholde eller lenke til) ulike typer aktiviteter/oppgaver, for å stimulere læringsprosessen. Dette kan være enkle spørsmål til refleksjon, små øvelser eller mer tradisjonelle øvingsoppgaver, gjerne basert på JExercise. De to første typene kan godt være en del av sida/temaet, mens større oppgaver bør ha en egen side, som det lenkes til.

Det finnes en standard bunntekst for oppgaver med egne sider, som kan inkluderes med Include-makroen

Kodingsoppgaver med JExercise

Mange av oppgavene handler om koding, hvor det er viktig å forsikre seg om at koden er korrekt, uavhengig om det blir sjekket av en læringsassistent. Studentene bør lære seg og derfor oppfordres til å skrive et enkelt hovedprogram hvor de kjører koden gjennom et representativt scenario. I tillegg kan en peke til evt. testkode basert på JExercise, som de kan kopiere inn i Eclipse og bruke både underveis og etterpå. I slike oppgaver kan det være lurt å referere til siden som forklarer om JExercise-oppgaver med excerpt-include-makroen, før en peker til selve testkoden (som gjerne ligger på github eller i annet repo), f.eks. slik:

Det finnes en standard bunntekst for JExercise-oppgaver med egne sider, som kan inkluderes med Include-makroen

Rikt innhold og bruk av makroer

En makro gir muligheten til annen type innhold og visning enn vanlig rik tekst, og Confluence-installasjonen har en rekke nyttige slike.

• Det er generell støtte for innhold fra nettsteder som YouTube og SlideShare
• En kan legge inn en eksplisitt innholdsfortegnelse som dekker hvilken som helst del av wiki-treet.
• excerpt og excerpt-include: excerpt kan brukes til å angi en tekstblokk (vanligvis setning) som essensen til en side, som kan gjenbrukes i andre sider med excerpt-include-makroen, f.eks. i oversiktstabeller.
• kode: Kodemakroen gir mulighet formattering og farging av kode i ulike språk.
• UML-diagrammer: plant-uml-makroen tilbyr et tekstformat for ulike UML-diagrammer, tilsvarende det vi har brukt i TDT4100. Dette gjør det raskt å lage små diagrammer hvor automatisk layout går greit.
• Diagrammer: Lucidchart-tjenesten har også støtte for Confluence, så en kan integrerer komplekse diagrammer i en wiki-side.
• metadata, metadata-list og metadata-report: disse kan brukes for å legge inn metadata i en side, som kan søkes frem og vises i en tabell i en side lenger opp i treet. Metadataene kan være synlige når de kan være informative for lesere, men kan gjøres usynlige og kun vises ved redigering.