Teknisk skriving

Dokumentasjon skrevet fra produktet, ikke fra spesifikasjonen

De fleste dårlige bruksanvisninger er skrevet ut fra et kravdokument eller en utviklers hukommelse. De beskriver hvordan funksjonen var ment å fungere, ikke skjermen brukeren faktisk ser, med sin omdøpte knapp og sitt ekstra bekreftelsessteg. Brukeren følger steg fire, finner ingenting som stemmer, og oppretter en sak.

Vi utfører hver prosedyre i produktet før vi skriver den, på en testkonto, i den rollen leseren vil ha. Der et steg oppfører seg annerledes enn teamet forventer, logger vi det, fordi dokumentasjonsarbeid rutinemessig avdekker feil ingen hadde rapportert. Den listen viser seg ofte å være like verdifull som dokumentasjonen.

Skill oppgaven fra forklaringen

En bruker som prøver å eksportere en faktura, vil ikke ha tre avsnitt om faktureringsmodellen først. En bruker som prøver å forstå faktureringsmodellen, vil ikke ha en nummerert liste over klikk. Å blande de to i én artikkel gjør begge vanskeligere å finne og tregere å lese.

Vi deler innholdet i oppgaver (hvordan gjøre én ting), konsepter (hvordan noe virker og hvorfor) og referanse (innstillinger, felt, grenser, feilkoder). Hver type har sin egen mal, så sidene holder seg konsistente etter at vi har overlevert og teamet ditt legger til den førtiende artikkelen.

Terminologilisten er det som holder settet sammenhengende over tid. Hvis grensesnittet sier 'arbeidsområde', sier dokumentasjonen aldri 'prosjekt' eller 'konto' om det samme. Det er et lite dokument som forebygger mesteparten av forvirringen brukerne rapporterer.

• Oppgaveartikler: ett mål, nummererte steg, resultatet brukeren skal se
• Konseptartikler: modellen bak en funksjon, med et diagram der det hjelper
• Referansesider: hvert felt, hver innstilling og grense, i en skannbar tabell
• Feilsøking: feilmeldingen som skrevet, årsaken og løsningen