Teknisk skrivning

Dokumentation skrevet ud fra produktet, ikke ud fra specifikationen

Det meste dårlige dokumentation er skrevet ud fra et kravdokument eller en udviklers hukommelse. Den beskriver, hvordan funktionen var tænkt til at virke, ikke den skærm, brugeren faktisk ser, med dens omdøbte knap og dens ekstra bekræftelsestrin. Brugeren følger trin fire, finder intet, der passer, og opretter en sag.

Vi gennemfører hver procedure i produktet, før vi skriver den, på en testkonto og i den rolle, læseren vil have. Når et trin opfører sig anderledes, end teamet forventer, logger vi det, for dokumentationsarbejde afdækker rutinemæssigt fejl, som ingen havde rapporteret. Den liste viser sig ofte at være lige så værdifuld som dokumentationen.

Adskil opgaven fra forklaringen

En bruger, der prøver at eksportere en faktura, vil ikke have tre afsnit om faktureringsmodellen først. En bruger, der prøver at forstå faktureringsmodellen, vil ikke have en nummereret liste af klik. Blander man de to i én artikel, bliver begge sværere at finde og langsommere at læse.

Vi opdeler indhold i opgaver (hvordan man gør én ting), begreber (hvordan noget virker og hvorfor) og reference (indstillinger, felter, grænser, fejlkoder). Hver type har sin egen skabelon, så siderne forbliver ensartede, efter vi overdrager, og dit team tilføjer den fyrretyvende artikel.

Terminologilisten er det, der holder sættet sammenhængende over tid. Hvis brugerfladen siger 'arbejdsområde', siger dokumentationen aldrig 'projekt' eller 'konto' om det samme. Det er et lille dokument, der forebygger det meste af den forvirring, brugerne rapporterer.

• Opgaveartikler: ét mål, nummererede trin, det resultat brugeren skal se
• Konceptartikler: modellen bag en funktion, med et diagram hvor det hjælper
• Referencesider: hvert felt, hver indstilling og grænse, i en overskuelig tabel
• Fejlfinding: fejlmeddelelsen som skrevet, dens årsag og løsningen