Techniniai tekstai

Dokumentacija, rašoma remiantis produktu, o ne specifikacija

Dauguma blogos dokumentacijos buvo rašoma remiantis reikalavimų dokumentu arba programuotojo atmintimi. Ji aprašo, kaip funkcija turėjo veikti, o ne ekraną, kurį mato vartotojas, su pervadintu mygtuku ir papildomu patvirtinimo žingsniu. Vartotojas seka ketvirto žingsnio instrukcija, neranda nieko atitinkančio ir atidaro bilietą techninei pagalbai.

Mes atliekame kiekvieną procedūrą produkte prieš ją aprašydami, naudodami testinę paskyrą ir rolę, kurią turės skaitytojas. Ten, kur žingsnis veikia kitaip nei tikisi komanda, mes fiksuojame tai kaip klaidą, nes dokumentacijos kūrimo procesas dažnai atskleidžia klaidas, apie kurias niekas nepranešė. Šis sąrašas dažnai pasirodo esąs ne mažiau vertingas nei pati dokumentacija.

Atskirkite užduotį nuo paaiškinimo

Vartotojas, bandantis eksportuoti sąskaitą faktūrą, nenori pirmiausia skaityti trijų pastraipų apie apskaitos modelį. Vartotojas, norintis suprasti apskaitos modelį, nenori gauti numeruoto paspaudimų sąrašo. Abiejų maišymas viename straipsnyje apsunkina abiejų informacijos paiešką ir sulėtina skaitymą.

Turinį skiriame į užduotis (kaip atlikti vieną veiksmą), konceptus (kaip kažkas veikia ir kodėl) ir reference (nustatymai, laukai, limitai, klaidos kodai). Kiekvienam tipui taikomas savo šablonas, todėl puslapiai išlieka nuoseklūs ir po perdavimo, kai Jūsų komanda pridės keturiasdešimtą straipsnį.

Terminų sąrašas yra tai, kas išlaiko nuoseklumą ilgalaikėje perspektyvoje. Jei sąsaja naudoja žodį „darbalaukis“, dokumentacijoje niekada nenaudojamas žodis „projektas“ ar „sąskaita“ tam pačiam dalykui. Tai nedidelis dokumentas, kuris padeda išvengti daugumos painiavos, apie kurią praneša vartotojai.

• Užduočių straipsniai: vienas tikslas, numeruoti žingsniai, rezultatas, kurį vartotojas turėtų pamatyti
• Konceptų straipsniai: funkcijos modelis su diagrama, kur ji padeda
• Reference puslapiai: kiekvienas laukas, nustatymas ir limitas, skenuojamoje lentelėje
• Trikdžių šalinimas: klaidos pranešimas, jo priežastis ir sprendimas