Tehniline kirjutamine

Dokumentatsioon, mis on kirjutatud toote vaatenurgast, mitte spetsifikatsiooni põhjal

Enamasti on halb dokumentatsioon kirjutatud nõuete dokumendi või arendaja mälu põhjal. See kirjeldab, kuidas funktsioon peaks tööle, mitte seda, mida kasutaja tegelikult ekraanil näeb, sealhulgas ümber nimetatud nuppu ja lisakinnituse sammu. Kasutaja järgib neljandat sammu, ei leia midagi sobivat ja avab pileti.

Teostame igat protseduuri tootes enne selle kirjutamist testkontol, selles rollis, mida lugejal on. Kui samm käitub erinevalt meeskonna ootustest, logime selle sisse, sest dokumenteerimise töö paljastab sageli vigu, mida keegi polnud varem teatanud. See loend osutub sageli sama väärtuslikuks kui dokumentatsioon ise.

Eraldage ülesanne seletusest

Kasutaja, kes proovib arvet eksportida, ei taha esmalt lugeda kolme lõiku arvustusmudelist. Kasutaja, kes püüab mõista arvustusmudelit, ei taha numbrilist loendit klikkidest. Kahe segamine ühes artiklis muudab mõlema leidmise raskemaks ja lugemise aeglasemaks.

Jagame sisu ülesanneteks (kuidas teha ühte asja), kontseptsioonideks (kuides asi töötab ja miks) ning viiteinfoks (seaded, väljad, piirangud, veakoodid). Igal tüübil on oma mall, nii et leheküljed jäävad järjekindlaks ka pärast üleandmist, kui teie meeskond lisab nelikümmenda artikli.

Terminoloogia loend hoiab komplekti kooskõlas ajas. Kui liides ütleb 'tööruum', siis dokumentatsioonis ei öelda kunagi 'projekt' ega 'konto' sama asja kohta. See on väike dokument, mis takistab enamikku segadusest, mida kasutajad teatavad.

• Ülesande artiklid: üks eesmärk, numbrilised sammud, tulemus, mida kasutaja peaks nägema
• Konsepst artiklid: funktsiooni taga olev mudel, diagrammiga seal, kus see aitab
• Viiteleheküljed: iga väli, seade ja piirang skannitavas tabelis
• Vigadeotsing: veateade sellisena nagu see on, selle põhjus ja lahendus