Tehnično pisanje

Dokumentacija, napisana iz perspektive izdelka, ne glede na specifikacije

Večina slabe dokumentacije je nastala na podlagi zahtevnikov ali spominov razvijalcev. Opisuje, kako naj bi funkcija delovala, ne pa zaslona, ki ga uporabnik dejansko vidi, s preimenovanim gumbom in dodatnim korakom potrditve. Uporabnik sledi četrtemu koraku, ne najde ničesar ustrezajočega in odpre zahtevek za podporo.

Vsako postopoma izvedemo v produktu preden ga zapišemo, na testnem računu, v vlogi, ki jo bo imel bralec. Kjer se korak obnaša drugače, kot pričakuje ekipa, to zabeležimo, saj delo na dokumentaciji pogosto razkrije napake, o katerih nihče ni poročal. Ta seznam je pogosto prav tako dragocen kot sama dokumentacija.

Ločite nalogo od razlage

Uporabnik, ki želi izvoziti račun, ne želi najprej treh odstavkov o ceniku. Uporabnik, ki želi razumeti cenik, ne želi številčenega seznama klikov. Mešanje obeh v enem članku oteži iskanje in upočasni branje.

Vsebino razdelimo na naloge (kako narediti eno stvar), koncepte (kako nekaj deluje in zakaj) ter referenčne strani (nastavitve, polja, omejitve, kode napak). Vsaka vrsta ima svoj predlogo, zato ostanejo strani dosledne tudi po prevzemu, ko vaša ekipa doda štiriintrideseti članek.

Seznam terminologije je tisto, kar ohranja celovitost skozi čas. Če vmesnik uporablja besedo 'delovni prostor', dokumentacija nikoli ne uporablja 'projekt' ali 'račun' za isto stvar. Gre za majhen dokument, ki prepreči večino zmede, ki jo uporabniki poročajo.

• Članki o nalogah: en cilj, številčeni koraki, rezultat, ki ga mora uporabnik videti
• Konceptualni članki: model za funkcijo, s diagramom, kjer pomaga
• Referenčne strani: vsako polje, nastavitev in omejitev v pregledni tabeli
• Odpravljanje težav: sporočilo napake takšno, kot je zapisano, njegov vzrok in rešitev