Slik skriver du gode brukerveiledninger for IT-tjenester

Veiledningene er til for brukerne

De som besøker nettstedet for IT-tjenester har gjerne en oppgave de trenger å løse. Brukerveiledningen skal gjennomgå én prosedyre, trinn for trinn, slik at brukeren kan løse oppgaven selv - uten å kontakte support. Veiledningene som ligger i hjelp-mappene er først og fremst hjelp til å bruke tjenestene, ikke dokumentasjon av dem.

Når du skriver en brukerveiledning må du ta utgangspunkt i at leseren ikke har den tekniske kunnskapen du har. Tenk igjennom:

• Hva lurer en vanlig bruker på?
• Hva ville du lurt på om du skulle ta i bruk tjenesten for første gang?
• Hvilke oppgaver blir tjenesten brukt til, og hvordan utføres de?

Veiledninger er ikke dokumentasjon

Ikke beskriv hva hver enkelt knapp gjør, men hvordan de løser oppgaven veiledningsartikkelen handler om - og ikke beskriv knapper som ikke er relevante for akkurat den oppgaven.

Du må forklare alt, trinnvis og slik at det er enkelt å forstå og lett å følge. Bruk tydelig språk og klare beskrivelser, uten stammespråk og forkortelser som bare de innvidde kjenner og forstår. Det hjelper lite om stoffet er tilgjengelig hvis det er i en språkdrakt som gjør det utilgjengelig.

Alle brukerveiledninger skal inneholde tjenestenavnet i artikkelens tittel. Da virker søket som det skal, og artiklene plukkes opp av søkemotorer. 

Eksempler
"Søk om tilgang til et TSD-prosjekt" 
"Svar og etterbehandling av data i Nettskjema"

Universell utforming

Brukerveiledningene skal være utformet slik at alle kan ha nytte av dem.

• Bruk klart og presist språk.
• Overskriftene skal brukes hierarkisk, fra H2 til H3 til H4. Er det bare ett nivå, skal du bruke H2. I avsnitt med undertitler brukes H2 over avsnittet, og H3 til undertitler.
  Neste avsnitt starter da med H2 igjen, og så videre. Overskrifter er ikke et estetisk valg, men et hjelpemiddel for lesbarhet.
• Lenketekster skal være handlingsdrivende, og bestå av hele setninger. De må si klart fra om hva brukeren kommer til når de klikker på lenken, og om de forlater UiOs nettsted. Går lenken til et dokument, for eksempel en PDF, må det stå i lenken. Eksempler: 
  "Klikk her for å gå til nettsiden med veiledninger om Office-pakken."
  "Les mer om personvern på Datatilsynets nettsider."
• Alle bilder skal ha en beskrivende alt-tekst. Alt-teksten skal gjengi informasjonen i bildet slik at også de som bruker leselist får med seg alt innhold på nettsiden. 

Les UiOs regelverk for universell utforming her.

Brukerreisen

Bruk litt tid på å kartlegge brukerreisen. Snakk med de som er support for tjenesten, og klargjør:

• Hvordan bruker brukerne tjenesten? Målet er å beskrive hvordan oppgavene skal utføres.
• Hva spør brukerne om når de kontakter support? 
• Finnes det brukerveiledninger for oppgavene brukerne trenger hjelp med? Er de gode nok? 
• Mangler det forklaring på noe som skaper mange spørsmål?

Se stoffet fra brukerens ståsted: hva lurer de på, hva trenger de hjelp med, og hvordan kan du beskrive det så det blir forstått?

Veiledningene må være optimalisert for søket

Brukerveiledningene har et eget søk. Det søker i artikler som ligger i mappen /hjelp/ og undermapper under hver tjeneste. Bruk malen Artikkel til alle brukerveiledninger. 

Søket søker i tittelfeltet i artikkelen og URL-en. Det betyr at du må ha navnet på tjenesten og ordene en bruker vil skrive i søkefeltet i tittelen eller URL-en til artikkelen. Tittelen skal alltid inneholde tjenestenavnet.

Tenk derfor nøye igjennom hvilken problemstilling artikkelen svarer på, og sjekk hvordan den dukker opp i søket. Du må altså lage en artikkel for hver problemstilling som det skal gis hjelp med.

• Alle brukerveiledninger legges i /tjenestenavn/hjelp/. 
• Bruk undermapper hvis du trenger å kategorisere for å holde orden, men det er ikke nødvendig.
• Ikke del opp brukerveiledninger for IT-tjenester i bolker for studenter og ansatte. Tjenestene er stort sett like for begge gruppene.
• Hver artikkel skal handle om kun ett tema og skal forklare fremgangsmåten til en oppgave brukere har behov for å løse.
• Tittelen må inneholde navnet på tjenesten - Zoom, Nettskjema, Outlook osv. - slik at den som søker ser hvilken artikkel som handler om riktig tjeneste i søket.

Forsider i undermapper

Hvis en undermappe har en index-fil som er laget med forsidemalen vil denne ikke bli plukket opp av søket. Bruk heller artikkelmalen til forsider i undermapper. 

Lenking til eksterne veiledninger

Tjenester som ikke er laget på UiO har som oftest en brukerveiledning på leverandørens nettside. Dersom denne er brukbar for våre brukergrupper, skal det ikke lages nye veiledninger på uio.no, men lenkes til denne fra tjenesteforsiden. Vi skal likevel lage veiledninger for:

• Spesielle funksjoner for UiO som ikke er beskrevet hos produsenten
• Personvern og hvilke data som kan sendes/brukes med tjenesten - denne kan også gjøres som en faktaboks på tjenesteforsiden.
• Minst en veiledningsside laget med artikkelmal, plassert i tjenestenavn/hjelp, som heter "Hjelp med tjenestenavn" og plukkes opp av søket på IT-tjenesteforsiden

Oppsett av veiledninger

Dersom veiledningen kan leses uten å rulle nedover trenger du ikke bruke trekkspillmeny eller innholdsfortegnelse.

Trekkspillmeny til alternativer

Trekkspillmenyer brukes der du skal velge en av flere framgangsmåter, eller der det er hensiktsmessig å dele opp prosessen og ta en del om gangen. Hver trekkspilloverskrift må vise tydelig hva punktet inneholder av informasjon. Du får da en oversiktlig artikkel som er lett å finne fram i.

Innholdsfortegnelse når alt skal leses

Innholdsfortegnelse brukes ved lengre artikler der alt skal leses, for eksempel retningslinjer der det er viktig at alt blir lest og forstått. Ved trinnvise veiledninger der brukeren må lese hele bør punktene nummereres. 

Index i hjelpmappen er landingsiden for tjenestens brukerveiledninger

En god landingside presenterer veiledningene slik at brukeren får en oversikt over hva tjenesten kan brukes til, og finner svar på oppgaven sin uten å kjenne konkrete søkeord. Index-siden i hjelpmappen – /tjenstenavn/hjelp/index –  er landingssiden for brukerveiledningene.

Er tjenesten stor, er det viktig å lage gode kategorier slik at brukerne lett finner hjelp til å løse oppgaven. Kategoriene kan være bruksområder for, eller funksjoner i tjenesten, men pass på at det ikke blir dokumentasjon av tjenesten. Veiledninger skal vise hvordan tjenesten brukes til å løse oppgaver.

Kategoriene kan lages som undersider i hjelpmappen, for eksempel tjenestenavn/hjelp/brukeradministrasjon - dersom det er flere artikler som omhandler temaet brukeradministrasjon.

Ikke bruk samlekategorier som "Tips & tricks", "Vanlige problemstillinger" og liknende. Vær tydelig på hva leseren får hjelp med. Som regel kan alle veiledninger listes under sin kategori på landingsiden. Er det en stor tjeneste med veldig mange veiledninger, kan hver kategori også ha en landingsside, men brukeren må alltid ha en klar vei til hjelp med oppgaven sin. Det skal være tydelig hvilken kategori de skal velge for å finne svar på oppgaven. 

Oppsett av landingsider

Denne siden skal ikke ha venstremeny. Gå inn på Visuell profil og velg Tilbakepeker for å fjerne venstremenyen.

Landingsiden settes opp med bokser/tiles: 
<ul class="navigation-links navigation-links-three-columns">.
Disse kan peke direkte til artikler, eller til undersider. Tenk igjennom hvilke kategorier og artikler du lenker til fra forsiden, og prioriter de som er mest brukt, eller som det er flest henvendelser til support om.

Landingsiden skal inneholde søkefelt som søker i tjenestens hjelpmappe, tilbakemeldingsboksen med tommel opp/tommel ned og kontaktinformasjon til support for tjenesten. Komponentene finner du her.

Innholdet i veiledningene

Les UiOs veileder for å skrive nettartikler her.

• Vær konsistent! Pass på at du skriver samme ord likt hver gang. Har du valgt deg en skrivemåte, så hold deg til den - i hele artikkelen, og i alle artikler i veiledningen. Bruk vennlig og menneskelig terminologi og stil.
• Ikke bruk feltet for innledning (ingressen) til å forklare hva veiledningen handler om. Det må komme fram av tittelen. Det viktige er at de beskrivende trinnene i veiledningen forklarer hva brukeren må gjøre for å – i dette tilfellet – skrive ut. 
• Del veiledningen inn i trinn og bruk nummererte punktlister for å vise hva brukeren må gjøre.
• Lange veiledninger bør ha innholdsfortegnelse – <div>Innhold</div>
• I veiledninger med enten-eller-trinn kan du bruke trekkspillkomponent (accordion) – <h2 class="accordion">Eksempeltekst</h2>  
  Bruk accordion kun der bruker skal velge mellom to eller flere oppgaver eller framgangsmåter, ikke der brukeren skal gjennomgå flere trinn. Da må også forrige og neste trinn være synlig uten klikking. 
• Bruk Overskrift 2 til avsnitt, og Overskrift 3 til underavsnitt.
• Bruk fet skrift og stor bokstav når du refererer til menypunkter, mapper, og kommandoer som skal klikkes på.
  Eksempel: "Du finner innloggingen under fanen Logg inn. Skriv inn UiO-brukernavn og passord og klikk Neste."
• Bruk sitattegn bare til sitater, og unngå dem ellers.
• Bruk nummererte punkter når du forklarer en framgangsmåte. Forklar i enkle trinn. Illustrer med bilder om mulig. 
• Om noe skal markeres i et bilde, bruk verktøyet PicPick eller lignende for å kunne lage pene ovale ringer eller piler for å markere.
• Bruk fet skrift for å markere det som er ekstra viktig i teksten.
• Skriv lenketekster som hele setninger med aktivt språk: Les mer om lenketekster i punkt 7 i denne sjekklisten.

Språk og terminologi

• Husk forskjellen på egennavn og fellesnavn! For eksempel heter tjenesten Nettskjema, mens du skal referere til "å fylle ut et nettskjema".
• Bruk aktivt språk og unngå fyllord og språkblomster som: "I tilfelle Y kan det være at det beste er å se nærmere på om det kan være fornuftig å..." Gå rett på sak!
• Skriv "Klikk på knappen" eller "For å x klikker du på knappen", ikke "Dersom man ønsker å utføre x, kan det klikkes på knappen.".
• Skriv "klikk på x-knappen", ikke "klikk x-knappen"
• Skriv "rull ned", ikke "scroll" eller "skroll"
• Skriv "logg inn", ikke "logg på"
• Skriv "skriv inn brukernavn i tekstfeltet" ikke "oppgi brukernavn" eller "angi brukernavn"
• Husk at det heter "e-post", ikke "epost".

Oppfølging av brukerveiledninger

• Sjekk veiledningen når du får supporthenvendelser der brukeren ikke har forstått veiledningen. Er den korrekt? Burde fremstillingen vært endret, slik at det blir lettere å forstå? 
• Oppdater veiledningene når du gjør endringer i tjenesten.
• Ta en årlig gjennomgang av hele brukerveiledningen, oppdatere artiklene