User:Hawk

Documentation

Under Editing

User:Hawk/org.zkoss.zul.listbox.DataLoader.class

Suspend

User:Hawk/Widget Event User:Hawk/Create Data Binding Programmatically User:Hawk/Tutorial Extension-UnitTest

Already published

1. Small_Talks/2011/December/MVVM_in_ZK6:in_Contrast_to_MVC
2. Small Talks/2012/January/Ajax GSP with ZK
3. Small Talks/2012/January/Enrich Grails Server Pages (GSPs) with ZK
4. Small_Talks/2012/January/MVVM_Extension:_Access_UI_Components_Inside_ViewModel
5. Small_Talks/2012/February/MVVM_in_ZK6:_Form_Binding
6. Small_Talks/2012/February/MVVM_in_ZK6:_Work_with_Spring
7. ZK Developer's Reference/MVVM (whole chapter)
8. Small Talks/2012/April/The Dawn of ZK Application Test Suite:Mimic Library
9. Small Talks/2012/April/Shining ZATS Mimic
10. ZATS Essentials
11. ZK Getting Started/Learn ZK in 10 Minutes
12. ZK Getting Started/Get ZK Up and Running with MVC
13. ZK Getting Started/Get ZK Up and Running with MVVM
14. Small Talks/2012/October/Binding with Collection and Selection
15. Small_Talks/2012/November/How_to_Apply_Responsive_Design
16. ZK Developer's Reference/Integration/Middleware Layer/Spring
17. ZK Developer's Reference/Integration/Middleware Layer/CDI
18. ZK Developer's Reference/Integration/Persistence Layer/Hibernate
19. ZK Developer's Reference/Integration/Persistence Layer/JPA
20. Small_Talks/2013/January/Building_User_Interface_Programmatically_with_Richlet
21. ZK Developer's Reference/Integration/Security/Spring Security
22. ZK Essentials
23. Small_Talks/2013/April/New_Features_of_ZK_Studio_2.0.0
24. ZK_Studio_Essentials
25. Small_Talks/2013/April/New_Features_of_ZATS_Mimic_1.1.0
26. Small_Talks/2013/June/ZK Binding Tracker - A Chrome Extension
27. ZK_Spreadsheet_Essentials (3.0.0)

Technical Writing

My Practice of Writing Documents

Preparation :

1. list assumptions for readers. To know which knowledge base which you build on and to decide which content the document should have.
2. write outline first.

   to be reviewed and discuss in bird's eye view

   check order of topic should have logical dependency

3. Pre-write quickly first.
4. need a technical proofreader to check technical concept
5. need an editor to check grammar and style.
6. Arrange topics with logic dependent orders, but leave some clues for those readers who skim a document
   1. Title
   2. Bold text
   3. Pictures
   4. Code highlight

Writing:

1. Topic sentence first, then supporting sentences
2. Describe the purpose or context at the beginning.
3. To start from a basic, simple concept or fewer concepts.
4. 1 paragraph presents 1 idea.
5. overall concept first, an example, then technical detail
6. keep consistent style in code or describing way in multiple related articles
7. keep consistent wording or terminology.
8. Summary at the end. (for small talk)
9. Choose Active, Precise Verbs
10. Check header, footer, TOC, subsections, references
11. 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 page width.
12. Code example:
    1. Re-using same application as an example. It can reduce user's burden to realize your article.
    2. Focus on a general case not a specific one.
    3. Keep as short as possible. Just extract the key part
    4. Demonstrate only key concepts and remove irrelevant codes.
    5. Demonstrate the correct API usage instead of work-around
    6. Keep number of codes as fewer as possible to reduce readers' burden.
    7. Highlight key points in descriptions of code example. (Because most engineers read code first instead of text)
    8. give short description for a code snippet for its purpose
    9. leave related variables declaration
    10. Line number first, then description because it's easier to look up descriptions upon lines, e.g. Line 13: this line's description
13. In Wiki page style, words before TOC is like preface. The "overview" should belong to one part of content and should be made as a header.
14. When using third party library, specify its version
15. Store example codes in a version control repository. They can be changed or verified in the future.
16. use an editor with a spell checker
17. Write directly on wiki page instead of writing in a word processor.
18. create a separate book for new version instead of modifying original books

    e.g. for version 3.0.0 - http://books.zkoss.org/wiki/Documentation:Books/ZK_Spreadsheet_Essentials_3

Learning Resource

English Writing:

• The Elements of Style, William Strunk, Jr ., 1918
• Purdue University Online Writing Lab
• search "grammar girl" for grammar tips

Technical Writing:

• 柯泰德線上英文論文編修訓練服務
• 寫作大師的秘密聖經： 一次解決所有英文寫作問題

Problem

• no offline editor
• no version control
• verbose syntax
• pdf edition cuts code

potential tool: http://gitbookio.github.io/javascript/basics/comments.html

ZK Documentation Format

• No version history table for a page having subsections links. (e.g. ZK_Developer's_Reference/Event_Handling)

Message Template

Standard:

Note: note message

Deprecated:

[i] Note: note message

Warning: warning message

Not Work sample:

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

Font design

http://3.7designs.co/blog/2008/06/10-examples-of-beautiful-css-typography-and-how-they-did-it/

Deprecated

User:Hawk/Simple ZK deprecated

User:Hawk/ZK Brief Intro and Simple Architecture

Supplement

• http://books.zkoss.org/wiki/User:Jimmyshiau

  Listbox, ZK container's default size, ID generator, Debug Client Error

• http://books.zkoss.org/wiki/Getting_Involved

  guide customers how to give us required data for debugging.

• User:Hawk/Selector Syntax
• User:Hawk/Session Timeout Configuration
• User:Hawk/Detach a Component under MVVM