Only at first the current docs might be difficult to understand. With difficult I mean someone with a non-programming/experience background, but there are in fact pretty good, focussed and easy to use.
I think user demos could be stored at jsfiddle and then somewhere on the page, next to the demos added by the dev team there could be links to user created demos (that could either end up as an official demo or just sit there for a while). So like, point for help to the channels like mailing list, irc perhaps and then when there are questions about usage of some method others can provide a small demo and put it up with some feature to also automatically notify the poster (or easier, want to keep track, use the mailing list). The demo link on mootools/docs could be combined with the original question if this would be a good 'addition' I think comments are nice but yes it would need good moderation and who has the time for that? I've got stuff from the php comments as well, great useful stuff, but there's indeed also outdated stuff, let alone running discussions.. those should be out of the comments if there were any. ...I'm just thinking out loud On May 22, 3:50 pm, fakedarren <[email protected]> wrote: > This is something we (I) want to improve on, sure. > > http://mootools.fakedarren.com/docs/Element/Element/ > > One of the biggest requests from our > survey<http://mootools.net/blog/2010/12/05/mootools-survey/>was that people > would like to see inline demos, so this integrates the demo > runner <http://mootools.net/demos/> too. > > I've not really gone into this too much; I am using XSL to transform the > current markdown docs we have, into other forms, because I think we're > actually pretty happy with the simplicity of using markdown for our docs. We > could add more structure to our markdown but I doubt we would be able to > convince everyone to move into another format. > > But the general thought behind it is that if you were to go to a page like > Fx.Tween <http://mootools.fakedarren.com/docs/Fx/Fx.Tween> you get a nice > summary of the methods available, and you than then delve in further to the > methods that interest you, and with demos we can make it easier to scan a > class or module, and give more detail for specifics. Sometimes some of the > details get lost because there is too much information on any one page. > > The git repository can be found > here<https://github.com/fakedarren/mootools-docs> > . > > With regards to comments.....this has been discussed endlessly before. It > sounds great but the reality is not as rosy as it seems. It would need > heavily moderating to be of real use; you could have a system whereby > comments only exist for a couple of weeks; if the comment is really > insightful, we adjust the documentation accordingly. But just look at the > PHP documentation; yes there is some great stuff in the user comments. There > is also some terrible stuff in there. > > But as arian says we already have the ability for any and all users to > comment and / or adjust our documentation. It's all freely available on > github <https://github.com/mootools/mootools-core/tree/master/Docs>. We > welcome all and any feedback. > > This is something that I wish to improve on - free time has been an issue > lately - so this thread is of great interest to me, keep the comments > coming! > > Cheers > Darren
