Redactare tehnică

Documentație scrisă din produs, nu din specificație

Majoritatea documentației proaste a fost scrisă pe baza unui document de cerințe sau a memoriei unui dezvoltator. Descrie cum trebuia să funcționeze funcția, nu ecranul pe care îl vede utilizatorul, cu butonul redenumit și pasul suplimentar de confirmare. Utilizatorul urmează pasul patru, nu găsește nimic potrivit și deschide un tichet.

Parcurgem fiecare procedură din produs înainte de a o scrie, pe un cont de test, în rolul pe care îl va avea cititorul. Dacă un pas se comportă altfel decât se așteaptă echipa, îl consemnăm, pentru că lucrul la documentație scoate frecvent la iveală erori despre care nimeni nu raportase. Lista aceasta se dovedește adesea la fel de valoroasă ca documentația.

Separați sarcina de explicație

Un utilizator care vrea să exporte o factură nu vrea mai întâi trei paragrafe despre modelul de facturare. Un utilizator care vrea să înțeleagă modelul de facturare nu vrea o listă numerotată de clicuri. Amestecarea celor două într-un singur articol face ambele mai greu de găsit și mai lente la citire.

Împărțim conținutul în sarcini (cum faci un lucru), concepte (cum funcționează ceva și de ce) și referință (setări, câmpuri, limite, coduri de eroare). Fiecare tip are propriul șablon, astfel încât paginile rămân consecvente după predare, iar echipa dumneavoastră adaugă al patruzecilea articol.

Lista de terminologie este ceea ce păstrează setul coerent în timp. Dacă interfața spune „spațiu de lucru”, documentația nu spune niciodată „proiect” sau „cont” pentru același lucru. Este un document mic care previne cele mai multe confuzii raportate de utilizatori.

• Articole de tip sarcină: un singur obiectiv, pași numerotați, rezultatul pe care utilizatorul ar trebui să îl vadă
• Articole conceptuale: modelul din spatele unei funcționalități, cu o diagramă acolo unde ajută
• Pagini de referință: fiecare câmp, setare și limită, într-un tabel ușor de parcurs
• Depanare: mesajul de eroare așa cum apare, cauza și soluția