Actually, this is exactly why I like the code completion in Komodo
Edit -- it has exactly what Arieh proposes. Perhaps the docs could have
a simple toggle between 'light' and 'complete' that simply toggles the
visibility of the full function documentation as it currently stands,
and have a basic outline for each function that's always available.
On 18/08/2010 7:04 PM, אריה גלזר wrote:
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]
<mailto:[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]
<mailto:[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 <http://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 <http://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 <http://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
<http://mootorial.com/wiki> is a
> better starting point.
>
> Tim.
--
Arieh Glazer
אריה גלזר
052-5348-561
5561
--
Not sent from my Apple πPhone
