2008/08/07

How to Write a Good Technical Documentation

Writing good documentation always hard! But you can make it better.

DO:

  • Fully understand the situation, and know the 5 W's:
    "Who, What, Where, When, and Why".

  • KISS: Keep It Simple and Stupid
  • Write agenda before you start

  • Keep the technical integrity
  • Add reference links for all the shared knowledge

  • Use diagram to show the complex logical
  • Use table to show the structured information
  • Compare the different design alternatives
  • Use bulletin and numbered list to express the idea

  • Write a good looking document
  • Have a good template
  • Use named style to control the format
  • Always do spelling/grammar check
  • Tidy your documentation

  • Ask for comments from others
  • Track changes between the reversions

DON'T:
  • Write long sentence or paragraph
  • Be afraid to delete some pieces
  • Be afraid to reconstruct sections
  • Be afraid to spend more time

Miscellanea:
  • Ask for others' help, and help others
  • Eats your own dog food
    Read it once more when you feel it were finished
发表评论