Guidelines for Technical Writing

Developer guide and education is more important than expected to the learning curve and performance of the application developer.

  • Use formal style in statement.
    • . Try to use intuitive and easy-to-read statement.
    • . Try to use exact and consistent words and terms.
  • Write guidelines from the viewpoint of application developer.
    • . Don't describe framework internal which application developers may not know.
    • . Keep consistent viewpoints.
  • Design the subjects and overall structure before writing details.
    • . Write down the table of contents first.
  • Adopt overview and detail pattern.
    • . There are patterns also in documentation.
  • Use lists and tables as possible.
    • . Lists are effective for describing process, arranging important points and cautions.
    • . Tables are effective for summarizing key-value style or hierarchical contents.
  • Don't use images as possible.
    • . Images are hard to maintain and update.
    • . Images are easy to understand at first sight but tend to shade details and exactness.
    • . Images are prone to waste volume of documents and make it difficult to transform documents.
  • Use non-trivial and consistent examples.
    • . Trivial examples can't make developers move fast to actual application.
    • . Examples should be flexible and scalable as the framework grows.
    • . Think of PetClinic sample appl. in spring framework's reference and PetStore sampl appl. in iBATIS' manual.
  • Try to derive and find out principles and techniques for excellent documentation.
    • . Be creative.
  • Establish effective and efficient documentation system.
    • . Think of docbook, wiki or other solutions and best practices.


Post a Comment