Bidra til Dapla-manualen
Alle i SSB kan bidra til denne manualen. Endringer må godkjennes av noen i Team Statistikktjenester eller Alex Crozier (akc@ssb.no). 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.
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!
Tittelblock og nyhetsinnlegg
I dapla-manualen har vi noen konvensjoner vi følger. En av de er å lage en title block som det kalles på quarto sin nettside.
Vi ber våre bidragsytere om å lage en lik block med overskrift og datoen artikkelen ble endret. Åpner man filen til denne siden ser det på dette tidspunktet slik ut:

Manualens egen nyhetssiden skal oppdaters med et innlegg når det kommer nye artikler. Det er ikke nødvendig å lage en sak om at en side har blitt oppdatert, med mindre endringene er omfattende. Nyhetssiden er i Quarto sitt blog-format. Fremgangsmåten er enkel og beskrives i quarto sin artikkel om blogger. Ellers anbefales det å ta en titt på hvordan det gjøres i dapla-manualen. Alex Crozier (akc@ssb.no) er ansvarlig for nyhetssiden og kan kontaktes dersom man trenger hjelp.
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 outputen 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 eller Alex (akc@ssb.no) om du lurer på noe.