I would say the real problem isn't with the docs, as much as they are with the lack of a good into guide withing the mootools site. The main mootools page does lack a reference to a good guide. The only two guides on the main page are 2 books that you can buy. Although the mootorial exists for quite a while and is a great intro to mootools, there is no highlighted link to it.
I would say that i agree that although the method list for each modoule is useful, it does lack their description. It would have been nice if i didn't have to read the full method docs to know if it's what I'm looking for. This can be done by a tooltip that could look like this: Array.indexOf[item [,from]) returns the index of item in array not sure if tooltips are the way to go but you get what i mean. anyway, I know good docs are extremely hard to manage, and the moodocs are still my second favorite after PHP's (which are definitely the best). and also - I would love to help improving them if help is needed (so this won't be just me asking others to do a job i want to get done) On Wed, Aug 18, 2010 at 11:12 AM, Savageman <[email protected]> wrote: > 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. > -- Arieh Glazer אריה גלזר 052-5348-561 5561
