How to write a good documentation

I am a newbe in Dojo... just tried to start. I already know JQuery little JQuery beause it is not that frightening to read the documentation. Lately when I developed several open source programs. I have got some comments about the documentation of my project.

He told me that he choose this: https://github.com/caolan/async library because of the documentation.

My documentation before: https://github.com/shimondoodkin/node-inflow/blob/77cc16467760d6eb80842d0b2da64b9b33b53ee7/README.md

My documentation after: https://github.com/shimondoodkin/node-inflow/wiki

I have learned few things:

• He told me that i have to use capital letters at the beginning of sentences. It makes it easier to read long texts.
• To have table of contents in each page - this is the main issue.
• To have description of arguments for each function
• To put one simple example per function not many.
• To make a page for a function to add all other examples.
• To put the documentation in a wiki.
• Have a design that supports understanding of hierarchical structure of information (see jquery left menu http://api.jquery.com/category/selectors or http://nodejs.org/api.html - the menu is fine but text is messy).
• Make access to documentation information quick like quick search.
• make videos describing how to begin use.

also he said that there are several php frameworks there is nothing additional in codeigniter except the a good documentation. http://codeigniter.com/user_guide/

for example other framework with a less good manual: http://www.symfony-project.org/doc/1_4/