Teknisk skrivning

Dokumentation skriven från produkten, inte från specen

De flesta dåliga dokumentationer skrevs utifrån ett kravdokument eller en utvecklares minne. Den beskriver hur funktionen var tänkt att fungera, inte skärmen användaren faktiskt ser, med sin omdöpta knapp och sitt extra bekräftelsesteg. Användaren följer steg fyra, hittar inget som stämmer och öppnar ett ärende.

Vi utför varje procedur i produkten innan vi skriver den, på ett testkonto, i den roll läsaren kommer att ha. När ett steg beter sig annorlunda än vad teamet förväntar sig loggar vi det, eftersom dokumentationsarbete rutinmässigt avslöjar buggar som ingen hade rapporterat. Den listan visar sig ofta vara lika värdefull som dokumentationen.

Separera uppgiften från förklaringen

En användare som försöker exportera en faktura vill inte ha tre stycken om faktureringsmodellen först. En användare som försöker förstå faktureringsmodellen vill inte ha en numrerad lista med klick. Att blanda de två i en artikel gör båda svårare att hitta och långsammare att läsa.

Vi delar upp innehållet i uppgifter (hur man gör en sak), begrepp (hur något fungerar och varför) och referens (inställningar, fält, gränser, felkoder). Varje typ har sin egen mall, så sidorna förblir konsekventa efter överlämningen och ditt team lägger till den fyrtionde artikeln.

Terminologilistan är det som håller uppsättningen sammanhängande över tid. Om gränssnittet säger "arbetsyta" säger dokumentationen aldrig "projekt" eller "konto" om samma sak. Det är ett litet dokument som förebygger det mesta av den förvirring användarna rapporterar.

• Uppgiftsartiklar: ett mål, numrerade steg, resultatet användaren ska se
• Konceptartiklar: modellen bakom en funktion, med ett diagram där det hjälper
• Referenssidor: varje fält, inställning och gräns, i en överskådlig tabell
• Felsökning: felmeddelandet som det står, dess orsak och åtgärden