Technická dokumentace

Dokumentace psaná z produktu, ne ze specifikace

Většina špatné dokumentace vznikla z dokumentu s požadavky nebo z paměti vývojáře. Popisuje, jak měla funkce fungovat, ne obrazovku, kterou uživatel skutečně vidí, s přejmenovaným tlačítkem a dalším krokem potvrzení. Uživatel postupuje podle čtvrtého kroku, nenajde nic odpovídajícího a otevře tiket.

Každý postup v produktu nejprve provedeme, než o něm napíšeme, na testovacím účtu a v roli, kterou bude mít čtenář. Kde se krok chová jinak, než tým očekává, zaznamenáme to, protože práce na dokumentaci běžně odhalí chyby, které nikdo nenahlásil. Ten seznam se často ukáže být stejně cenný jako samotná dokumentace.

Oddělte úkol od vysvětlení

Uživatel, který se snaží exportovat fakturu, nechce nejprve tři odstavce o fakturačním modelu. Uživatel, který se snaží pochopit fakturační model, nechce číslovaný seznam kliknutí. Míchání obojího v jednom článku ztěžuje hledání i čtení.

Obsah dělíme na úkoly (jak něco udělat), koncepty (jak něco funguje a proč) a referenci (nastavení, pole, limity, chybové kódy). Každý typ má vlastní šablonu, takže stránky zůstanou konzistentní i poté, co vám je předáme a váš tým přidá čtyřicátý článek.

Seznam terminologie je to, co udržuje celek dlouhodobě soudržný. Pokud rozhraní říká „pracovní prostor“, dokumentace nikdy neoznačuje stejnou věc jako „projekt“ nebo „účet“. Je to malý dokument, který zabrání většině zmatení, která uživatelé hlásí.

• Články s úkoly: jeden cíl, číslované kroky, výsledek, který má uživatel vidět
• Články s koncepty: model stojící za funkcí, s diagramem tam, kde to pomůže
• Referenční stránky: každé pole, nastavení a limit v přehledné tabulce
• Řešení problémů: chybová zpráva tak, jak je napsaná, její příčina a oprava