Jika anda telah dicaj dengan menulis dokumen yang sepatutnya mengarahkan orang lain bagaimana melakukan sesuatu, cara hari ini melakukan lebih atau kurang melemparkan kaedah lama ke luar tetingkap.
1. Pengepala Besar Bombastic
Anda akan melihat pengepala di PCMech, seperti yang betul di atas ayat ini, adalah besar. Ini kerana mereka lebih mudah untuk melihat, membaca dan mengetahui di mana anda berada dalam dokumen itu.
2. Less Words
Cara salah:
Dokumentasi berikut menerangkan cara menggunakan dan mengendalikan Fanny Whacker 2000.
Cara yang betul:
Arahan mengenai cara menggunakan Fanny Whacker 2000
Sentiasa ingat frasa ini apabila menulis dokumentasi: GET TO THE POINT SEPERTI CEPAT SEBAGAI POSIBLE.
3. Langkau rujukan yang tidak berguna
Sekiranya rujukan tidak ada kaitan dengan arahan teras mengenai apa yang anda cuba huraikan, seperti:
Untuk maklumat lanjut mengenai Turnip Twaddler Fanny Whacker 2000, sila lihat dokumen FU, subseksyen ID10T.
… jangan lakukan itu.
4. Tarikh itu. Sentiasa.
Tarikh apabila dokumentasi ditulis hendaklah berada di kawasan footer setiap halaman. Sekiranya ia dokumen elektronik, tarikh itu ditunjukkan dua kali. Sekali pada permulaan, sekali pada akhir.
Anda boleh menulis ini sebagai "Terakhir Semakan (memasukkan tarikh di sini)".
5. Amaran harus selalu diposkan sebelum titik tidak dikembalikan
Sekiranya terdapat sesuatu dalam dokumentasi anda yang boleh merosakkan / memusnahkan / menghapuskan sesuatu jika dilakukan dengan tidak betul, maklumat ini hendaklah diletakkan terus selepas arahan yang diberikan, berada dalam penglihatan biasa (bermaksud pada halaman yang sama) dan beraksen.
Contoh:
Langkah 5. Membersihkan Fanny Whacker 2000
Pedang FW2000 perlu dibersihkan dengan lembut menggunakan kain lembut yang tidak kasar.
AMARAN: Hanya gunakan pelarut bebas ammonia untuk menghalang FW2000 dari meletup dan mengakibatkan kematian anda yang tidak lama lagi.
Pada nota akhir, dokumentasi yang baik bukan dari super-deskriptif mengenai setiap perkara yang mungkin dibayangkan. Baca dokumentasi anda dan tanya diri anda, adakah ia mengarahkan dengan betul? Sekiranya jawapannya adalah ya, soalan seterusnya, apakah ia mengarahkan dengan cepat ? Jika ya, dokumentasi adalah baik.
