Difference between revisions of "User:Hawk"

From Documentation
Line 46: Line 46:
 
# [[ZK_Spreadsheet_Essentials]] (3.0.0)
 
# [[ZK_Spreadsheet_Essentials]] (3.0.0)
  
 +
=Technical Writing =
 
== My Practice of Writing Documents ==
 
== My Practice of Writing Documents ==
 
# Write directly on wiki page instead of writing in a word processor.
 
# Write directly on wiki page instead of writing in a word processor.
 +
# write outline first
 +
#:
 
# Pre-write quickly first.
 
# Pre-write quickly first.
 
# create a separate book for new version instead of modifying original books
 
# 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
 
#: e.g. for version 3.0.0 - http://books.zkoss.org/wiki/Documentation:Books/ZK_Spreadsheet_Essentials_3
−
# Store example codes in a version control repository instead of dropping them. They will be changed in the future.
+
# Store example codes in a version control repository. They can be changed or verified in the future.
 
# 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.
 
# 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.
 +
# use spell checker
 +
# list assumption for readers
  
 
== Writing Checklist ==
 
== Writing Checklist ==
Line 61: Line 66:
 
# Give the overall concept first, then the detail of implementation.
 
# Give the overall concept first, then the detail of implementation.
 
# keep consistent style in code or describing way in multiple related articles
 
# keep consistent style in code or describing way in multiple related articles
 +
# keep consistent wording or terminology.
 
# Summary at the end. (for small talk)
 
# Summary at the end. (for small talk)
 
# Check header, footer, TOC, subsections, references
 
# Check header, footer, TOC, subsections, references
Line 77: Line 83:
 
## Highlight key points in descriptions of code example. (Because most engineers read code first instead of text)
 
## 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
 
# When using third party library, specify its version
 +
 +
== Learning Resource ==
 +
* The Elements of Style, William Strunk, Jr ., 1918
 +
* [http://www.chineseowl.idv.tw/html/lla.html 柯泰德線上英文論文編修訓練服務]
 +
* [https://owl.english.purdue.edu/owl/ Purdue University Online Writing Lab]
 +
*
  
  
Line 89: Line 101:
 
** Line number first, then description because it's easier to look up descriptions upon lines.
 
** Line number first, then description because it's easier to look up descriptions upon lines.
 
*** e.g. Line 13: this line's description
 
*** e.g. Line 13: this line's description
 +
  
 
== ZK Documentation Format ==
 
== ZK Documentation Format ==
 
* No version history table for a page having subsections links. (e.g. [[ZK_Developer%27s_Reference/Event_Handling]])
 
* No version history table for a page having subsections links. (e.g. [[ZK_Developer%27s_Reference/Event_Handling]])
 +
  
  

Revision as of 01:56, 31 July 2014

Documentation

Under Editing

Under Review

Ready for Publish

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

  1. Write directly on wiki page instead of writing in a word processor.
  2. write outline first
  3. Pre-write quickly first.
  4. 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
  5. Store example codes in a version control repository. They can be changed or verified in the future.
  6. 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.
  7. use spell checker
  8. list assumption for readers

Writing Checklist

  1. Describe the purpose or context at the beginning.
  2. To start from a basic, simple concept or fewer concepts.
  3. 1 paragraph presents 1 idea.
  4. Give the overall concept first, then the detail of implementation.
  5. keep consistent style in code or describing way in multiple related articles
  6. keep consistent wording or terminology.
  7. Summary at the end. (for small talk)
  8. Check header, footer, TOC, subsections, references
  9. Check overall article's layout.
  10. 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.
  11. 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)
  12. When using third party library, specify its version

Learning Resource


Document Style

  • Image
    • make it center
    • Shrink the size for too big one
  • Code snippet
    • give short description for a code snippet for its purpose
    • Extracted the key part
    • leave related variables declaration
    • Line number first, then description because it's easier to look up descriptions upon lines.
      • e.g. Line 13: this line's description


ZK Documentation Format


Message Template

Standard:

Icon info.png 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

User:Hawk/temp


Supplement

Retrieved from "https://www.zkoss.org/_w/index.php?title=User:Hawk&oldid=42113"