Bidra til Dapla-manualen

Alle i SSB kan bidra til denne manualen. Endringer må godkjennes av noen i Team Statistikktjenester, si gjerne i fra at det ligger en PR å se på. Vi trenger bidrag med alt fra språkvask, nye artikler og andre gode initiativer! Har du lyst til å bidra, men er ikke helt sikker på hva du kan bidra med? Ta en titt på issues i GitHub-repoet.

Warning

Denne nettsiden er åpen og hvem som helst kan lese det som er skrevet her. Hold det i tankene når du skriver.

Forutsetninger

Man trenger basis git kompetanse, det ligger en fin beskrivelse av det på Beste Praksis siden fra KVAKK.
Man trenger en konto på Github, det kan man opprette ved å følge instruksjonene her.
Man kan lære seg Markdown (enkel tekst formatering), en fin oversikt finnes her.
Verktøyet Quarto burde installeres for å kunne se endringene slik som de ser ut på nettsiden. Installasjon instruksjoner finnes her.

Fremgangsmåten

Klone repoet

terminal

git clone https://github.com/statisticsnorway/dapla-manual.git

Lage en ny gren
Gjøre endringen
Kjør følgende og følge lenken for å sjekke at alt ser bra ut på nettsiden:

terminal

quarto preview dapla-manual

Åpne en PR
Be noen å gjennomgå endringen og eventuelt godkjenne den
Merge PRen
Etter et par minutter skal din endring være synlig!

Embedded notebooks

Quarto tilbyr å legge ved (embed) notebooks inn i nettsiden. Dette er en fin måte å dele kode og output på. Men det krever at vi tenker gjennom hvor output`en genereres. Siden Dapla-manualen renderes med GitHub-action, så ønsker vi ikke å introdusere kompleksiteten det innebærer å generere output fra kode her. I tillegg er det mange miljø-spesifikke konfigurasjoner som bestemmer hvordan output kan genereres. Derfor anbefaler vi følgende tilnærming når man skal legge ved en notebook til et kapittel:

Logg deg inn i miljøet du ønsker å bruke.
Klone ned repoet til Dapla-manualen.
Opprett en notebook i mappen ./dapla-manual/notebooks/notebook-navn.ipynb
Skriv kode og generer output som du ønsker. Husk å bare bruke data som alle har tilgang til eller de kan generere selv.
Embed output i kapitlet du ønsker iht til denne beskrivelsen
På toppen av notebooken lager du en raw-celle der du skriver:

notebook

---
freeze: true
---

Kjør denne notebooken fra terminalen med kommandoen:

terminal

quarto render ./notebooks/<notebook-navn.ipynb> --execute

Dette sikrer at vi kan se output etter at boken bygges i GitHub Actions. Husk at notebooks ikke blir strippet for output på vanlig måte, slik at kun åpne data skal benyttes.

Spør Team Statistikktjenester om du lurer på noe.