Tehniskā rakstība

Dokumentācija, kas uzrakstīta no produkta perspektīvas, nevis no specifikācijas

Lielākā daļa sliktās dokumentācijas ir uzrakstīta, balstoties uz prasību dokumentiem vai izstrādātāja atmiņu. Tā apraksta, kā funkcija bija paredzēta darboties, nevis to, ko lietotājs redz ekrānā – ar pārdēvētām pogām un papildu apstiprinājuma soli. Lietotājs seko ceturtajam solim, neatrod nekādu atbilstību un atver biļeti.

Mēs veicam katru procedūru produktā pirms tās aprakstām, testkontā, ar tādu lomu, kāda būs lasītājam. Ja kāds solis darbojas savādāk, nekā gaidīts, mēs to reģistrējam, jo dokumentācijas sagatavošanas process regulāri atklāj kļūdas, par kurām nebija ziņots. Šis saraksts bieži vien ir tikpat vērtīgs kā pati dokumentācija.

Atdaliet uzdevumu no skaidrojuma

Lietotājam, kurš mēģina eksportēt rēķinu, nav nepieciešami trīs pāragi par maksājumu modeli. Savukārt lietotājam, kurš vēlas saprast maksājumu modeli, nav vajadzīga skaitļota klikšķu saraksta. To sajaukums vienā rakstā padara abas informācijas daļas grūtāk atrodamas un lēnāk lasāmas.

Mēs sadalām saturu uzdevumos (kā izdarīt vienu lietu), konceptos (kā kaut kas darbojas un kāpēc) un atsauces materiālos (iestatījumi, lauki, limiti, kļūdu kodi). Katram tipam ir savs veidne, tāpēc lapas paliek konsekventas arī pēc tam, kad esam nodevušas darbu, un Jūsu komanda pievieno četrdesmito rakstu.

Terminoloģijas sarakss ir tas, kas nodrošina kohērentību ilgtermiņā. Ja interfeiss izmanto vārdu 'darba vide', dokumentācijā nekad netiks lietots 'projekts' vai 'konts' vienai un tai pašai lietai. Tas ir neliels dokuments, kas novērš lielāko daļu no apjukuma, ko lietotāji ziņo.

• Uzdevumu raksti: viens mērķis, numurēti soļi, rezultāts, ko lietotājam būtu jāredz
• Koncepta raksti: funkcijas pamatmodelis ar diagrammu tur, kur tas palīdz
• Atsauces lapas: visi lauki, iestatījumi un limiti skenējamā tabulā
• Kļūdu novēršana: kļūdas ziņojums tāds, kāds tas ir, tā cēlonis un risinājums