Műszaki dokumentáció

A termék alapján írt dokumentáció, nem a specifikáció alapján

A rossz dokumentáció nagy részét követelménydokumentum vagy a fejlesztő emlékezete alapján írták. Azt írja le, hogyan kellett volna működnie a funkciónak, nem azt a képernyőt, amelyet a felhasználó valójában lát, az átnevezett gombbal és a plusz megerősítő lépéssel. A felhasználó követi a negyedik lépést, nem talál semmit, ami egyezne, és hibajegyet nyit.

Minden eljárást végrehajtunk a termékben, mielőtt leírnánk, egy tesztfiókon, abban a szerepkörben, amelyben az olvasó lesz. Ahol egy lépés másként viselkedik, mint amire a csapat számít, naplózzuk, mert a dokumentációs munka rendszeresen olyan hibákat hoz felszínre, amelyeket senki sem jelentett. Ez a lista gyakran ugyanolyan értékesnek bizonyul, mint maga a dokumentáció.

Válassza szét a feladatot a magyarázattól

Aki számlát próbál exportálni, nem akar először három bekezdést a számlázási modellről. Aki a számlázási modellt próbálja megérteni, nem akar számozott kattintáslistát. A kettő egy cikkben való keverése mindkettőt nehezebben megtalálhatóvá és lassabban olvashatóvá teszi.

A tartalmat feladatokra (hogyan csináljunk meg egy dolgot), fogalmakra (hogyan és miért működik valami) és referenciára (beállítások, mezők, korlátok, hibakódok) bontjuk. Minden típusnak saját sablonja van, így az oldalak egységesek maradnak, miután átadjuk, és a csapata hozzáírja a negyvenedik cikket.

A terminológiai lista az, ami hosszú távon egységesen tartja a készletet. Ha a felület azt mondja, hogy „munkaterület”, a dokumentáció soha nem mond ugyanarra „projektet” vagy „fiókot”. Ez egy kis dokumentum, amely megelőzi a felhasználók által jelentett zavarok nagy részét.

• Feladatcikkek: egy cél, számozott lépések, az eredmény, amelyet a felhasználónak látnia kell
• Fogalomcikkek: a funkció mögötti modell, ahol segít, ábrával
• Referenciaoldalak: minden mező, beállítás és korlát, jól áttekinthető táblázatban
• Hibaelhárítás: a hibaüzenet úgy, ahogy megjelenik, annak oka és a javítás