Hvordan bidra til Dapla-manualen

Sist endret

November 22, 2024

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.

Gjør du nyhetsverdige endringer må du også lage et nyhetsinnlegg i nyhetsdelen av manualen. Mer om det lenger nede.

Forutsetninger

Tittelblock

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:

Skjermbilde av tittelblock.
Figur 1: Tittelblock for denne siden.
Interne lenker

Når man skal lenke til andre artikler i manualen bør gjør man det slik: [artikkel om ssb-project](../ssb-project.qmd)

Legg merke til at vi lenker til .qmd-filen, ikke den genererte .html-filen, ei heller manual.dapla.ssb.no

Nyhetsinnlegg

Manualens egen nyhetssiden skal oppdaters med et innlegg en nyhetsverdig endring på Dapla skjer - for eksempel når manualen får en ny artikkel. 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.

Hvordan skrive nyhetsinnlegg?

Utover det tekniske er det særlig tre ting å tenke på:

Kategoriser innlegget. Om du skriver en ny artikkel bør du kategorisere innlegget med ‘dapla-manual’, slik det har blitt gjort i dette nyhetsinnlegget.

Bruk emojier for å kategorisere For å gjøre det enda lettere for lesere bruker vi emojier i starten av overskriften som sier noe om nyhetens natur. Trykk win + . for å få opp emojier. Her er emojiene vi tar i bruk og deres betydning:

📄 Ny dokumentasjon (f.eks artikkel i manualen) 🚀 Endringer på Dapla lab 🐍 Python 🐍📚 Pythonpakke ❗ Driftsmelding 🥳 Ny lansering

Er du usikker på hvilken emoji du skal bruke kan det fint droppes - eller så kan man ta i bruk nye emojier.

Skriv kort og ha en forklarende overskrift

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

Teknisk remgangsmåte

  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!