Hopp til innhold

Hvordan skrive dokumentasjon

For at designsystemet skal fungere må systemdokumentasjonen være god. Hvis utviklere og designere ikke vet hvilke muligheter og begrensninger som finnes i systemet, kommer de til å gjøre feil og dobbeltarbeid.

Vi prøver å levere god dokumentasjon for Jøkul, og vi har bygd opp rammeverket for dokumentasjon slik at Jøkul har det som trengs og sånn at vi kan levere en smidig utvikleropplevelse. Det skal bare være én kilde til sannhet.

Markdown

All dokumentasjon på portalen en skrevet med språket Markdown. Dette er et markeringsspråk som lar deg definere strukturen i det du skriver ved hjelp av enkle tegn i teksten. Her følger en kort introduksjon til de viktigste funksjonene. For en mer utfyllende gjennomgang med eksempler anbefaler vi Markdown Guide. Hvis du vil ha forhåndsvisning mens du skriver kan du bruke online-verktøy som f.eks. Dillinger.

Avsnitt og utheving

Du markerer et nytt avsnitt ved å sette inn en tom linje. Dette må du også gjøre før og etter alle overskrifter. Hvis du ønsker å sette inn et linjeskift uten å starte et nytt avsnitt, må du legge inn to mellomrom på slutten av linjen, hvis ikke vil linjeskiftet bli ignorert.

Utheving av tekst gjøres ved å sette stjerne eller understrek før og etter teksten som skal utheves: Både _dette_ og *dette* vil vises som dette. Ønsker du kraftigere utheving kan du bruke to stjerner eller to understreker: Både __dette__ og **dette** vil vises som dette.

Overskrifter

Overskrifter må stå på en egen linje, og være et eget avsnitt (altså med tom linje over og under). Overskriftsnivået angis med firkanttegn (hashtags) på starten av linjen, etterfulgt av et mellomrom. Antall firkanttegn angir overskriftsnivået, for eksempel:

# Overskrift på nivå 1

Lister

Punktlister angis med en stjerne eller bindestrek foran hvert punkt, etterfulgt av et mellomrom. Ikke bruk tomme linjer mellom punktene. Du kan skape lister med innrykk ved å sette inn fire mellomrom før listepunktet:

- Et punkt
    - Et innrykket punkt
- Et nytt punkt på toppnivå

Nummererte lister angis med tall og punktum på starten av linjen, etterfulgt av mellomrom. Du må starte på 1, men tallene du skriver ellers har ingen påvirkning på resultatet; det vil alltid bli stigende rekkefølge:

1. Det første punktet
8. Det andre punktet (selv om det står åtte)
1. Det tredje punktet (selv om det står 1)

Slik dokumenterer vi komponentene

For å dokumentere en ny komponent i portalen oppretter du en .mdx fil i <pakkenavn>/documentation. MDX er en versjon av Markdown som lar deg bygge inn React direkte i dokumentet. MDX-filen plukkes opp automatisk av portalen hvis den har en title definert i frontmatter (se under). I tillegg til tittelen forventer portalen å finne pakkenavnet (uten @fremtind/jkl-) til stilpakken og React-pakken. Lenker til GitHub blir generert automatisk ut fra disse. Du kan ha flere slike dokumentasjonsfiler i samme pakke dersom det for eksempel eksporteres flere komponenter.

---
title: Accordion
react: accordion-react
scss: accordion
---

Komponentdokumentasjonen skal bestå av en kort beskrivelse av komponentens tiltenkte funksjon og bruk, et eksempel på komponenten, og eventuell utfyllende dokumentasjon av bruk med eksempler der det trengs. For å kunne vise eksempel på komponenten, samt riktig og feil bruk av den, har vi laget noen hjelpekomponenter som automatisk er tilgjengelige når du skriver komponentdokumentasjonen. Disse beskrives nærmere under.

Komponenteksempler

For å vise eksempel på komponenten i portalen har vi laget en hjelpekomponent som heter ComponentExample. Denne kan du bruke i komponentdokumentasjonen uten å måtte importere den eksplisitt. Den tar inn en React-komponent som inneholder eksempelet du vil vise. ComponentExample tar i tillegg inn en liste over egenskaper som skal kunne skrus av og på i eksempelet, samt en liste over verdier som kan ha flere valg:

<ComponentExample component={DittEksempel} knobs={
    boolProps={["En verdi", "En annen verdi"]}
    choiceProps={[{
        name: "Verdi med valg",
        values: ["verdi1", "verdi2"],
        selectedValue: 0 // indeksen til forhåndsvalgt alternativ
    }]}
} />

Disse verdiene blir vist som valg i portalen med avkrysningsbokser eller radioknapper. De valgte verdiene blir eksponert for eksempelet slik at du kan bruke dem til å endre egenskaper:

// typer for verdiene:
import { ExampleComponentProps } from "doc-utils";

export function DittEksempel({ boolValues, choiceValues }: ExampleComponentProps) {
    boolValues["En verdi"] // boolsk verdi
    choiceValues["Verdi med valg"] // "verdi1" eller "verdi2"

    // Bruk dem i eksempelet slik:
    <MinKomponent boolskEgenskap={boolValues["En verdi"]} valgEgenskap={choiceValues["Verdi med valg"]} />
}

Eksempler på riktig og feil bruk

For å vise eksempler på riktig og feil bruk kan du bruke hjelpekomponenten DoDontExample. Denne kan du bruke i komponentdokumentasjonen uten å måtte importere den eksplisitt. Komponenten tar inn type eksempel (do eller dont), et bilde som viser eksempelet, og en tekst som beskriver bruken:

<DoDontExample type="do" description="Kun én primærknapp" image="/assets/do-donts/button-do-1.png" />

Bildet legger du i mappen static under portal-pakken i prosjektet.