On 18 Aug 2010, at 09:12, Savageman wrote: > - An introduction for each module, which explains what it's used for > and how to use it
I think each class (/ "Component" ) in the docs has a one or two sentence intro. Is that not enough? > - Some complete examples in relation to the module As far as I can tell, almost every function has an example. > - A quick rereference, with a list of all the functions inside the > module, associated with a little explanation (something like the > download page as index would be really a really good starting point!). > That allows a quick overview of what do each function, without wasting > time. I'm not sure on this one. I think in the case of PHP such a thing is required more due to the cryptic naming scheme of functions. I suspect the authors of MooTools have gone to fair lengths to choose clear and consistent names for functions and events (well, I think maybe apart from $chk and $splat for me!), so such a requirement isn't needed. I think also, it is assumed people have read the MooTorial, and so are familiar with the general concepts used in MooTools, and so what a particular function name is likely to do. > - Each function is on a single different page. That allows comments, > which are very valuable. This comments thing is interesting. Perhaps a "show comments" button would be good for people to add or see comments, while keeping pages concise? > The MooTools docs looks like a raw text/plain document in comparison. > Each page has too much text, that doesn't make you want to read it. I fear you are wanting contradictory things. Adding things you mention above, an introduction, comments, and more examples, will add text, and not reduce it. (I'm a bit fan of the conciseness.) > It never says "API reference" or "API doc". It just says "docs" so i'm > not really expecting "just" an API doc. Actually... due to the examples I would say it is a little bit more than "just" an API doc. Still, such confusion will only last for a few seconds one you looked at them? Also, are you suggesting you wouldn't have your criticisms if the title was "API Reference" ? ;-) > When you click on it you > directly arrive on the Core module API, which doesn't welcome you very > well. I would prefer to not have to skip over a welcome page and/or every time I use the docs! I would actually say the demos are much more lacking than the docs, and as you mentioned, perhaps a way of merging them would be good. Perhaps links to or embeds of jsfiddle-s for each function / class would be good for beginners.... Michal.
