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.