Ext Documentation

[narven]

Hi everybody,

I just wanna say that i really like Ext, it's a great lib, congrats to the dev team.

But... since i've started using Ext... (about 1 mounth ago... yeah.. really newbie), i've come to be really really annoyed about the "Ext Documentation".
Your Ext documentation is not a documentation... its a "pocket reference". It's impossible to a newbie like me to make something while looking at the documentation.
Maybe it's good for someone that already know's the code and just needs some little tips, but for a newbie... it's a nightmare.
I know that there are some couple of tuts, demos, and some other stuff. But i think (and this is my opinion) that you should put more examples in the documentation... maybe... for example a master example for the Ext.form.Form and then an example for each function, giving choices to the user, showing how to use a specific function or event, etc.

I'm saying this because it's hard... not to understand the documentation... but to transport what i've read to my code. And i think it would help alot the BIG HELPERS of the forum, that sometimes... go over the edge with some questions from newbies like me :P

something that would be good... and this is just an example... something like this... http://www.php.net/manual/en/function.htmlentities.php
there's alot of people information bellow the explaning of the function, many examples. I can go there.. and i automatic.. understand.. the code.


Of course this is my newbie opinion.
PS: sorry for my english

[justinbezanson]

I hear you. I also am finding it very hard to determine the correct syntax from the documentation and also what version of Ext certain tuts are using. It is a bit confusing. On a better note Ext does rock and I love it. Great work!

[mystix]

:-? have you checked out the Ext 2.0 examples here (http://extjs.com/deploy/dev/examples)?

[mikegiddens]

I'm saying this because it's hard... not to understand the documentation... but to transport what i've read to my code. And i think it would help alot the BIG HELPERS of the forum, that sometimes... go over the edge with some questions from newbies like me

Normally it is easier for the big guys to just point you in the right direction. Most of the newbie questions are repetitive and can normally be found in older even much older posts then most think to look for. You have to realize that when this started it was just Jack and now there is a whole team that is dedicated to improving things day by day. I don't even want to know how much time Jack spends a day coding and he still is on the forums with advice.

All I can say is it doesn't happen overnight and stick with it. Start small and don't try to do everything at once. Make a checklist and complete one task at a time and really take advantage of firebug.

-Mike

[narven]

Most of the newbie questions are repetitive and can normally be found in older even much older posts then most think to look for.

True... true... but most of the time... we spend hours and hours searching the forum for something... and we probably will find it... but do we really need to spend all that time looking for something that has been already answered ten times... when the anwser bye the 3

[Animal]

There are dozens and dozens of examples if you look in the examples directory! Almost everything is covered.

[jay@moduscreate.com]

The problem about that is that a lot of the stuff is pretty complex for newbs. i've been there, it's frustrating to do simple things sometimes when you don't know what to look for.

Like fx for example. if you're new - where do you look for examples?

[brian.moeskau]

Like fx for example. if you're new - where do you look for examples?

LOL, fx is one of the classes that actually does have extensive inline examples ;). Fx methods are more function-oriented than normal Ext classes, so it makes sense.

We try to provide examples where we can, but this is one of those areas where whatever we do, it's never going to be enough for everyone. There are tons of existing examples, tutorials, API docs, a wiki, a few videos.... and yet people want more...

[jay@moduscreate.com]

LOL, fx is one of the classes that actually does have extensive inline examples ;). Fx methods are more function-oriented than normal Ext classes, so it makes sense.

We try to provide examples where we can, but this is one of those areas where whatever we do, it's never going to be enough for everyone. There are tons of existing examples, tutorials, API docs, a wiki, a few videos.... and yet people want more...

eh, it was just an example ;)

Folks want you to pretty much debug hundreds of lines of code for one extra comma. there is always room for improvment. keep that attitude and EXTJS will continue to climb the charts! :)

for the record: I love the new doc base and the community. If i need to know more about an object, i just console.log() it :)

[SeaSharp]

I have had another bad day with Ext and believe the documentation is the root of my problem. There is no doubt that that the documentation has improved a lot recently but I am troubled that the Ext Team believes the docs are now sufficient.

To highlight some problems with the docs I have encountered in the last 24 hours:

No example showing how to populate a form with a server supplied JSON object.
No definition of the JSON format to achieve the above.

A misleading tutorial that indicates form fields should be populated line by line, when in fact there are two superior alternatives e.g. internal JSON fetch-auto populate or push of a Record object.

Ext.data.Record.getChanges() states "Gets a hash of only the fields that have been modified since this record was created or commited".

What sort of hash is this? Ext's own custom collection class, an array or something else? After wasting 30 minutes I worked out that a

[brian.moeskau]

If you found a tutorial that was missing some explanation, did you update it accordingly? If you found API doc issues, did you post them in the API doc bugs thread?

I never said that the docs are sufficient -- I said that regardless of what we do, it will never be enough for everyone. Please try to have some perspective on this -- we have a HUGE code base, and documenting it is a never-ending task. We are doing the best we can, and it is constantly evolving and improving. It will not happen overnight.

[mikegiddens]

SeaSharp,

As you know 2.0 is still in beta and I can tell you brian, nwhite, and mystix are making document changes each and every day so as the betas progress the documentation will only get more complete. I also understand it is hard to get started and expect to spend hours and days trying to figure out how to do something. It just takes time like anything and after 6 months I still don't know everything and still learning every day.

The problem with already knowing how to do stuff is to explain in simple terms to new members since it is hard to tell how much they know. That will always be the problem and progressing from the newbie status takes time. Just keep coding and the worst thing you might have to do is read the Ext code top to bottom a couple of times. ;) That always helps understand what it is doing. I hear too many new guys wanting to just make stuff without knowing or reading everything at least once to know what Ext is actually doing behind the scenes.

Just hang in there it only gets easier.

-Mike

[SeaSharp]

If you found a tutorial that was missing some explanation, did you update it accordingly?
As an Ext newbie it did not feel right to blunder into someone's tutorial and claim it illustrated the least favoured method of populating a form. Anyhow I did better than that, yesterday I wrote a new tutorial but I want to sit on it for a few days as I learn more about Ext forms handling. Is there a route for getting a proposed tutorial peer reviewed before public upload?

If you found API doc issues, did you post them in the API doc bugs thread?
I have posted there about two other V2.0 doc bugs this week but felt now is the wrong time to overload the docs fixing process with reworded alternative attribute definitions.

We are doing the best we can, and it is constantly evolving and improving. It will not happen overnight.
I know, I am just frustrated because I feel Ext is on the verge of something big but the current docs act as a break on that growth potential. While searching the forums on that JSON/form bind question I noticed 3 others asking the same question and not getting beyond 10 posts in total, was that 3 lost support contracts because the developers went elsewhere?

[narven]

HI,


If you found a tutorial that was missing some explanation, did you update it accordingly? If you found API doc issues, did you post them in the API doc bugs thread?

Yes, i've corrected some errors in the wiki, not Ext errors, but Javascript sintaxe errors. I don't think that a newbie guy should be doing tutorials, or writting to wiki, because it's going to probably make mistakes. And other people are going to read it, if it is another newbie... it's just going to get worse. I will probably writte some stuff in the wiki.. but.. later.. when i feel confortable with Ext, or part of it.


Please try to have some perspective on this -- we have a HUGE code base, and documenting it is a never-ending task. We are doing the best we can, and it is constantly evolving and improving. It will not happen overnight.

I completly understand that. and i know that you are trying to do your best =D> When i started this post it was to give my opinion on something that i think lacks work, or could be improved, specialy because i think it's better to improve the documentation now (in the aspect that i've written before) than latter... because... functions will never stop to apear, new cool stuff, etc (thanks to the Ext Team =D> ).