Pokud jste byli obviněni z psaní dokumentu, který má poučit někoho jiného, jak něco udělat, dnešní způsob, jak to udělat, víceméně hodí staré metody z okna.
1. Big Bombastic Headers
Všimněte si, že záhlaví na PCMech, jako je ten, který je nad touto větou, je obrovské. Je to proto, že jsou snáze vidět, číst a vědět, kde jste v dokumentu.
2. Méně slov
Špatným směrem:
Následující dokumentace vysvětluje, jak používat a provozovat Fanny Whacker 2000.
Správná cesta:
Pokyny k používání Fanny Whacker 2000
Při psaní dokumentace si vždy pamatujte tuto frázi: ZÍSKEJTE BOD, POKUD JE MOŽNÉ RYCHLE.
3. Přeskočte zbytečné reference
Pokud odkaz nemá nic společného s hlavní instrukcí toho, co se pokoušíte popsat, jako například:
Další informace o Turnad Twaddler Fanny Whacker 2000 najdete v dokumentu FU, pododdíl ID10T.
… Nedělej to.
4. Datum. Vždy.
Datum, kdy byla dokumentace napsána, by mělo být v zápatí každé stránky. Pokud se jedná o elektronický dokument, zobrazí se datum dvakrát. Jednou na začátku, jednou na konci.
Můžete to napsat jako „Naposledy revidováno (zde vložte datum)“.
5. Varování by měla být vždy zveřejněna před okamžikem, kdy se nevrátí
Pokud je v dokumentaci něco, co by při nesprávném provedení mohlo něco poškodit / zničit / zničit, měla by být tato informace umístěna bezprostředně po uvedené instrukci, měla by být na dohled (což je na stejné stránce) a akcentována.
Příklad:
Krok 5. Čištění Fanny Whacker 2000
Pádla FW2000 by měla být jemně očištěna měkkým hadříkem, který neobsahuje brusné materiály.
VAROVÁNÍ: Používejte pouze rozpouštědlo neobsahující amoniak, abyste zabránili explozi FW2000 a následnému předčasnému úmrtí.
A konečně, dobrá dokumentace nepředstavuje super-popisný popis každé jednotlivé možné věci. Přečtěte si svou dokumentaci a zeptejte se sami sebe, dává pokyn správně? Pokud je odpověď ano, je další otázka, dá to instrukci rychle ? Pokud ano, dokumentace je dobrá.
