I don't even know how you can remotely compare the MooTools doc to the PHP one... They're really different, and the PHP one is one of the best (the best?) I've been able to see. The PHP documentation has: - An introduction for each module, which explains what it's used for and how to use it - Some complete examples in relation to the module - 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. - Each function is on a single different page. That allows comments, which are very valuable.
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. It never says "API reference" or "API doc". It just says "docs" so i'm not really expecting "just" an API doc. When you click on it you directly arrive on the Core module API, which doesn't welcome you very well. On Aug 17, 8:41 pm, Tim Wienk <[email protected]> wrote: > > 1. it's indeed very complete, but we need time to get the information > > we want. > > 2. it's lacking a "Getting started". > > 4. Also demos are missing. I think they should be merged with the > > documentation. > > The mootools.net/docs are API docs. It's not a guide. That's why there > is no 'Getting started' section and that's why there are no demos. > > > 3. There is no quick reference: when we click a class on the left, all > > the methods are shown on the right and all their associated > > documentation is on the same page. As an index page for a class, it > > would be nicer to list all the methods from it, associated with a > > little explanation (like on php.net). > > I don't really see this point. When you click on a Class, all methods > are mentioned on the right, clicking that gets you straight to the > explanation. > > > 5. There is no categorized topics. The structure organisation only on > > the classes structure. For instance, the Element class has too much > > methods for a human to reasonably make it looks good in his mind. > > Maybe some categories like on the jQuery documentation would be nice > > (attributes, traversing, manipulation). > > The documentation is categorized the way MooTools itself is > categorized, by modules/packages (whatever you want to call them). > This is also because they're API docs. You get to pick the modules you > want, and use those, and you'll find the documentation for those > modules right where you'd expect them. Perhaps taking a look > athttp://mootools.net/corewill clear things up a bit. > > I do agree that this doesn't help people who just want to download > MooTools and use it with plugins X, Y and Z. But then another question > is whether those people are MooTools' target audience. Like Arieh > mentioned, for more guide-like explanations, mootorial.com/wiki is a > better starting point. > > Tim.
