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.

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

1. Klone repoet

terminal

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

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

terminal

quarto preview dapla-manual

1. Åpne en PR
2. Be noen å gjennomgå endringen og eventuelt godkjenne den
3. Merge PRen
4. 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:

Figur 1: Tittelblock for denne siden.

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:

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

notebook

---
freeze: true
---

7. 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.