Technické písanie

Dokumentácia písaná z pohľadu produktu, nie zo špecifikácie

Väčšina zlých dokumentácií bola napísaná podľa požiadaviek alebo z pamäte vývojára. Opisuje, ako mala funkcia fungovať, nie obrazovku, ktorú používateľ skutočne vidí, s premenovaným tlačidlom a ďalším krokom potvrdenia. Používateľ sa dostane ku štvrtému kroku, nájde nič zhodujúce sa a otvorí tiket.

Každý postup v produkte si pred jeho popisom overíme na testovacom účte v rolí, akú bude mať čitateľ. Tam, kde sa krok správa inak, než tím očakával, evidujeme to, pretože práca na dokumentácii bežne odhalí chyby, ktoré nikto neprihlásil. Tento zoznam sa často ukáže byť rovnako cenný ako samotná dokumentácia.

Oddelte úlohu od vysvetlenia

Používateľ, ktorý sa snaží exportovať faktúru, nechce najprv tri odseky o modely fakturácie. Používateľ, ktorý sa snaží pochopiť model fakturácie, nechce číslovaný zoznam kliknutí. Zmiešanie oboch do jedného článku sťažuje ich nájdenie a spomaľuje čítanie.

Rozdeľujeme obsah na úlohy (ako vykonať jednu vec), koncepty (ako niečo funguje a prečo) a referenčné stránky (nastavenia, polia, limity, kódy chýb). Každý typ má vlastnú šablónu, takže stránky zostávajú konzistentné aj po tom, čo ich odovzdáme a váš tím pridá štyridsiaty článok.

Zoznam terminológie je tým, čo udržiava súbor koherentný v čase. Ak rozhranie hovorí 'pracovný priestor', dokumentácia nikdy nehovorí 'projekt' alebo 'účet' pre tú istú vec. Je to malý dokument, ktorý bráni väčšine záverov, ktoré používatelia reportujú.

• Články o úlohách: jeden cieľ, číslované kroky, výsledok, ktorý by mal používateľ vidieť
• Konceptové články: model za funkciou, s diagramom, kde pomôže
• Referenčné stránky: každé pole, nastavenie a limit v prehľadnej tabuľke
• Riešenie problémov: chyba tak, ako je zapísaná, jej príčina a oprava