Norsk teknisk redaktør — klarspråk, AI-markører, anglismer, fagtermer, mikrotekst
Retningslinjer for norsk bokmål i teknisk dokumentasjon, UI-tekst og PR-beskrivelser.
Basert på Språkrådets klarspråk-prinsipper, ISO 24495-1 og Navs språkprofil.
Start med konklusjonen. Bakgrunn og kontekst kommer etterpå.
❌ Etter en grundig evaluering av flere alternativer, der vi vurderte
både ytelse, driftskompleksitet og kostnad, har vi besluttet å
gå videre med CNPG som Postgres-operator.
✅ Vi bruker CNPG som Postgres-operator. Den gir oss automatisk
failover, backup og oppgradering uten nedetid.
❌ Vi foretar en gjennomgang av implementasjonen.
✅ Vi gjennomgår implementasjonen.
❌ Det er behov for en vurdering av sikkerhetsaspektene.
✅ Vi må vurdere sikkerheten.
Fjern mønstre som avslører KI-generert tekst.
| AI-markør | Gjør i stedet |
|---|---|
| "banebrytende", "revolusjonerende" | Konkrete beskrivelser |
| "robust", "helhetlig", "sømløs" | Skriv om eller dropp |
| "spiller en avgjørende rolle" | Gå rett på sak |
| "effektivisere prosessen" | Si hvilken prosess og hvordan |
| "digital transformasjon" | Si hva som endres konkret |
| "sikre at" | "passe på", "gjøre X mulig" |
| "sørge for at" | "gjøre", "passe på" |
| "muliggjøre" | "gjøre mulig", "gi rom for" |
| "understreke behovet for" | Si behovet direkte |
| "hensynta" | "ta hensyn til" |
| "implementere" | "innføre", "ta i bruk", "lage" |
| "ivareta" | "ta vare på", "følge opp" |
| "tilrettelegge for" | "legge til rette for", "gjøre det enklere" |
| "understøtte" | "støtte" |
Varier overgangene mellom setninger og avsnitt. Unngå å starte mange setninger etter hverandre med:
Bruk i stedet konkrete subjekter: "Teamet ...", "Koden ...", "Tjenesten ..."
image, cluster, node, container, deployment, release, plugin, backup, failover, rollback, upstream, downstream, secret, namespace, pod, pipeline, workflow, runtime, framework, pull request, merge, commit, branch, rebase, endpoint, payload, token, scope, bug, hotfix, patch
feilsøking, oppgradering, sikkerhetskrav, vedlikehold, bidragsytere, brukervennlighet, tilgjengelighet, kodegjennomgang, avhengighet
Bruk bindestrek: image-bygg, CI-pipeline, deploy-steg, Kafka-topicet, GitHub-repoet
| Anglisme | Norsk alternativ |
|---|---|
| "adressere et problem" | "løse", "fikse", "ta tak i" |
| "på slutten av dagen" | "til syvende og sist" eller dropp |
| "ta eierskap til" | "ha ansvar for" |
| "delivere" | "levere" |
| "har du noen input?" | "har du innspill?" |
| "involvere" (overbrukt) | "ta med", "inkludere" |
| "deploye" | "rulle ut" |
| "shippe" | "levere", "sende ut" |
| "reviewe" | "gå gjennom", "se over" |
| "release" (som verb) | "gi ut", "rulle ut" |
| "onboarde" | "ta imot", "sette i gang" |
| "pitche" | "presentere", "foreslå" |
| "tracke" | "følge med på", "spore" |
| "booste" | "øke", "forbedre" |
| "aligne" | "samkjøre", "enes om" |
| "triage" | "prioritere", "sortere" |
| Teksttype | Tone | Tips |
|---|---|---|
| ADR | Nøytral, teknisk | Kontekst → Beslutning → Konsekvenser. Ingen salgssnakk. |
| README | Direkte, vennlig | Start med hva appen gjør, deretter oppsett. |
| UI-tekst | Enkel, handlingsrettet | Korte setninger. Brukeren er "du". |
For commit-meldinger, se conventional-commit-skillen. For PR-beskrivelser, se pull-request-skillen.
API-kall, deploy-steg, CI-pipelinekl. 08–16, side 3–7❌ Det er viktig å påpeke at Kubernetes representerer et betydelig skritt
fremover innen container-orkestrering.
✅ Kubernetes orkestrerer containere. Vi bruker det til å kjøre og
skalere appene våre i clusteret.
❌ Vi må adressere dette problemet og ta eierskap til prosessen.
✅ Vi må fikse dette. Teamet har ansvar for å finne en løsning.
❌ Operasjonen kunne ikke gjennomføres grunnet manglende
obligatoriske feltverdier i skjemaet.
✅ Du må fylle ut alle påkrevde felt før du kan sende inn.
❌ Dette prosjektet representerer et innovativt verktøy som
muliggjør effektiv håndtering av søknader. Det er utviklet
med tanke på å sette brukeren i sentrum.
✅ Behandler søknader om foreldrepenger. Bygget med Kotlin/Ktor,
deployes til Nais.
❌ Vi har nå gjennomgått de ulike aspektene ved migrasjonen.
Som vi har sett, er det flere viktige hensyn å ta. Oppsummert
kan man si at en vellykket migrering krever grundig planlegging.
✅ (Kutt hele avsnittet. Leseren har allerede lest det du oppsummerer.)