Utvikling

Utviklingssidene er en teknisk veiledning for utviklere som lager tjenester ved hjelp av Altinns verktøy og API-er.

Målet er at innholdet ikke skal være en “dokumentasjon” på hvordan ting er gjort, men være “oppskrifter” på hvordan brukeren løser en oppgave. De generelle skriverådene gjelder også for utviklingssidene.

NB: Innholdet og sidene er under utvikling
Vi er ikke helt ferdige med disse ressursene ennå.

Målgruppe

Primær

  • Utviklere som jobber for tjenesteeiere
  • Andre utviklere som ønsker å bruke Altinns åpne API eller Digital post
  • Fagpersoner som jobber med tjenesteutvikling og ikke har utvikler-kompetanse

Sekundær

  • Prosjektledere, designere og andre som jobber med digitalisering av offentlige tjenester

Brukeroppgaver for utviklingssidene

  1. Har Altinn verktøy og API-er som er relevante for meg i digitaliseringsjobben?
  2. Hvordan kommer jeg i gang som utvikler?
  3. Trenger jeg noen tilganger?
  4. Er min etat/kommune tjenesteeier?
  5. Hvordan har andre brukt Altinn i digitaliseringsarbeidet?

Skriveprinsipper

  • Vi skriver direkte til brukeren (bruker «du»)
  • Vi skriver kort og konsist
  • Når vi introduserer Altinn-spesifikke ord forklarer vi alltid hva det betyr
  • Vi gir dem lette oppgaver først slik at brukeren kan føle mestring
  • Vi hjelper brukeren til å få ting gjort og sender brukeren videre til neste steg
  • Vi motiverer og deler opp oppgavene i flere deler
  • Vi informerer der innholdet kun er på engelsk

Huskeregler

  • Bruk tid på å finne ut av hva fagpersonene bruker slags ord og ikke bruk det som interne kaller ting.
  • Husk at brukeren kanskje kommer til siden fra en søkemotor
  • Ha som utgangspunkt at brukeren ikke vet noe om Altinn fra før
  • Ikke bruk interne prosjektnavn slik som for eksempel “Tjenester 3.0”. Dette kan evt. beskrives i teksten med forklaring til hva det er.
  • Husk at folk som ikke kjenner Altinn skal forstå innholdet

Generelle regler for innhold på utviklingssidene

Tittel og ingress

  • Bruk en tittel som beskriver innholdet. Dersom tittelen er et prosjektnavn, verktøynavn eller forkortelse skal dette forklares i teksten.
  • Ingressen skal gi tilstrekkelig informasjon slik at brukeren kjapt kan vurdere om innholdet er relevant.

Innholdsliste

  • Bruk innholdsliste for sider med mye innhold slik at brukeren kan skape seg et raskt overblikk. Dette gjøres i markdown-filen ved å sette toc:true i toppfeltet. Alle H2 vil da bli klikkbare titler i innholdslisten.

Innhold

  • Vær inkluderende og si det så enkelt som mulig, selv om innholdet er teknisk.
  • Bruk trinnvise oppskrifter der brukeren skal gjøre noe i en bestemt rekkefølge.
  • Forklar alltid hva som er neste steg for brukeren.
  • Utviklingsguider

    Hvert produkt har en utviklingsguide som skal sørge for at brukeren får en oversikt over hva som må til for å bruke dette produktet. Guiden skal skrives slik at det er lett å forstå hvilken rekkefølge du skal gjøre oppgavene i.

  • API

    API-dokumetasjonen skal gi veiledning for hvordan utviklere bruker APIet - både det som er åpent for alle og det som er tilgjengelig kun for tjensteeiere.

  • Verktøy

    Verktøy inkluderer brukerveiledning for TUL, SERES og Altinn Studio