We should have a standalone session talking about fileupload and link to fileupload component,
or mention all the usage that user need to know to the related component at least.

Related documents:

Fileupload component
http://books.zkoss.org/wiki/ZK_Component_Reference/Essential_Components/Fileupload

MenuItem component
http://books.zkoss.org/wiki/ZK_Component_Reference/Essential_Components/Menu/Menuitem

Button component
http://books.zkoss.org/wiki/ZK_Component_Reference/Essential_Components/Button

Event thread for FileUpload (Here's the toolbarbutton/button usage. )
http://books.zkoss.org/wiki/ZK_Developer%27s_Reference/UI_Patterns/Event_Threads/Fileupload

Here's a fiddle sample for menuitem but it's not working , not sure it's a bug or wrong usage. _#
http://zkfiddle.org/sample/2dml6rj/1-Test-menu-fileupload

ZK Demo
http://www.zkoss.org/zkdemo/file_handling/file_upload

The document for fileupload should contains the following section:

1.Fileupload samples ( Fileupload , button, toolbarbutton , menuitem usage.) (Take care the event thread.)

2.How could we handle the error message when fileupload fail. (Currently the way is very hardcore...)

3.What information we could get from uploaded file and how to do this,ex.file name ...etc
(Also what type we should get from Uploaded File. For example,for Image it's org.zkoss.image.Image.)

org.zkoss.util.media.Media media = event.getMedia();
if (media instanceof org.zkoss.image.Image) {

4.A sample for how to move the file to specific webapp folder , ex. webapp/img/uploaded/

5.more advance usage :
ex.Changing temp file size ,progress bar (including progressbar customization )...etc

6.trouble shooting

Upload is a very common usage and got to be more clear to save our user's time. (And also our time...)