Documentation

Under Editing

Write directly on wiki page instead of writing in a word processor.
Pre-write quickly first.
create a separate book for new version instead of modifying original books
1. http://books.zkoss.org/wiki/Documentation:Books/ZK_Spreadsheet_Essentials_3.x
Store example codes in a version control repository instead of dropping them. They will be changed in the future.

Describe the purpose or context at the beginning.
To start from a basic, simple concept or fewer concepts.
1 paragraph presents 1 idea.
Give the overall concept first, then the detail of implementation.
keep consistent style in code or describing way in multiple related articles
Summary at the end. (for small talk)
Check header, footer, TOC, subsections, references
Check overall article's layout.
Picture is better than words.
1. Picture should be elegant.
2. Picture should present just exactly enough information.
3. Set align to center.
4. Shrink size if a picture's width is wider than half of a page.
Code snippet:
1. Focus on a general case not a specific one.
2. Keep as short as possible.
3. Demonstrate only key concepts and remove irrelevant codes.
4. Demonstrate the correct API usage instead of work-around
5. Keep number of codes as fewer as possible to reduce readers' burden.
6. Highlight key points in descriptions of code example. (Because most engineers read code first instead of text)
When using third party library, specify its version

Standard:

Note: note message

Deprecated:

[i] Note: note message

Warning: warning message

Not Work sample:

/_w/images/e/e2/Icon_info.png