Ha olyan dokumentum megírásával vádolják, amely állítólag valakit másnak utasít arra, hogyan kell valamit csinálni, akkor a mai módszer úgy, hogy többé-kevésbé a régi módszereket dobja ki az ablakon.
1. Nagy bombastikus fejlécek
Észre fogja venni a PCMech fejléceit, mint például a mondat fölött jobbra, hatalmasak. Ennek oka az, hogy könnyebben láthatók, olvashatók és tudják, hol tartózkodnak a dokumentumban.
2. Kevesebb szó
Rossz irány:
Az alábbi dokumentáció ismerteti a Fanny Whacker 2000 használatát és működtetését.
Helyes utat:
Útmutatások a Fanny Whacker 2000 használatához
A dokumentáció írásakor mindig emlékezzen erre a mondatra: MEGJELENLEN A PONTRA, MELY LEHETSÉGES.
3. Átugorja a haszontalan referenciákat
Ha a hivatkozásnak semmi köze nincs ahhoz a fő utasításhoz, amelyet leírni próbál, például:
A Fanny Whacker 2000 fehérrépa-ikerrel kapcsolatos további információkért lásd az FU dokumentum ID10T alszakaszát.
… ne csináld ezt.
4. Dátumot. Mindig.
A dokumentáció elkészítésének dátumának minden oldal láblécében kell lennie. Ha ez elektronikus dokumentum, akkor a dátum kétszer jelenik meg. Egyszer az elején, egyszer a végén.
Ezt a következőképpen írhatja: "Utoljára felülvizsgálva (ide illessze be a dátumot").
5. A figyelmeztetéseket mindig a visszatérés nélküli pont előtt kell elhelyezni
Ha a dokumentációban van valami, amely helytelenül hajthatja végre, megsemmisítheti vagy megsemmisíthet valamit, akkor ezt az információt közvetlenül az utasítás után kell elhelyezni, látható látványban (ugyanazon az oldalon jelentve) és ékezetesnek kell lennie.
Példa:
5. lépés: A Fanny Whacker 2000 tisztítása
Az FW2000 eveit óvatosan, nem koptató, puha ruhával kell megtisztítani.
FIGYELMEZTETÉS: Csak ammóniamentes oldószert használjon az FW2000 felrobbanásának és a korai halálának elkerülése érdekében.
Végezetül: a jó dokumentáció nem az, hogy minden lehetséges elképzelésre szuper leíró jellegű. Olvassa el a dokumentációt, és kérdezd meg magadtól, hogy megfelelően tanítja? Ha igen, a következő kérdés az, hogy gyorsan utasít-e? Ha igen, a dokumentáció jó.
