PDA

View Full Version : API Docs Update



rossini
2 Apr 2007, 4:31 AM
Hello Everyone,

First of all, congrats on the new site and beta release. I downloaded de zip file but noticed that the API docs are still not up to date. Are there plans to synchronize the API docs with the new releases to come?

Frank
2 Apr 2007, 4:48 AM
Note: The documentation and samples will not be fully updated until the 1.0 final release. 8-|

2 Apr 2007, 4:52 AM
what's the point of releasing builds if the docs are not updated to reflect additions? :confused:

Jamie Avins
2 Apr 2007, 5:41 AM
what's the point of releasing builds if the docs are not updated to reflect additions? :confused:

Bug fixes and other priorities I'm sure... But I have to agree that the documentation is becoming woefully out of date...

brian.moeskau
2 Apr 2007, 9:27 AM
We can always stop releasing bug fixes altogether until the documentation is complete if that's your preference. Obviously, the people complaining about documentation have never actually written documentation...

EDIT: Upon re-reading, that sounded a bit harsh, so let me rephrase. A LOT of work has gone into building this new site, setting up a company structure, writing code, writing new examples, oh yeah, and updating documentation. We have a LOT of stuff to do, and there aren't many people on the team (only Jack and me full-time right now). So please have a little patience with us as we move toward the final release. Most frameworks don't have good documentation at all -- we're just saying that it's not there during alpha/beta. Most people find that to be reasonable.

rossini
2 Apr 2007, 10:08 AM
We can always stop releasing bug fixes altogether until the documentation is complete if that's your preference. Obviously, the people complaining about documentation have never actually written documentation...

Hahaha I

schmidetzki
2 Apr 2007, 10:54 AM
Most frameworks don't have good documentation at all

That is true, but should not be used a an argument here. The good documentation was one reason to give yui-ext a chance over other js-libs.

Therefore it is very important to have a documention at last shortly after release.
In the meantime every one like me must/can read the source code :-)

JeffHowden
2 Apr 2007, 11:48 AM
In the meantime every one like me must/can read the source code :-)

And, by reading the source code, you'll have an even better understanding of how it works than if you'd just referenced something in the docs. :D

brant
2 Apr 2007, 12:28 PM
I was wondering if there are plans to allow some user contributed documentation? I was thinking if the documentation had a commenting system similar to Jacks blog. Select users could see the comment bar and leave edits. Then someone from the Ext team could review them for inclusion. I have lots of personal notes about specific functions that I could add. I realize this is not a small project to do in itself but maybe helpful.

jack.slocum
2 Apr 2007, 12:33 PM
Brant, that is definitely going to happen it's just a matter of when. I have a few ideas for it. The actual commenting code isn't difficult, the most time consuming part would be the additional "online" documentation generator templates that could generate what is needed to make that work. 1 set of templates for the download and one set of templates for "live" docs online.

Draven
2 Apr 2007, 4:21 PM
I'd like to take an opportunity to show you guys what many think is the best run Open Source project going right now. They only just released v1.0 but have a look at all the "docs" they have :) (Note: I'm not suggesting you write a book before your 1.0 release, but most of the book docs existed pre 1.0 )

Not trying to promote symfony here either, just giving you guys an overview of some really great ideas and how they implemented them.

Wiki: http://trac.symfony-project.com/trac/wiki/
Plugins: http://trac.symfony-project.com/trac/wiki/SymfonyPlugins
Book: http://www.symfony-project.com/book/trunk
Tutorial: http://www.symfony-project.com/askeet
Ajax: http://www.symfony-project.com/tutorial/symfony_ajax.html
Mailing Lists: http://www.symfony-project.com/snippets/ (this is really cool, shared code snippets with comments)

cdomigan
2 Apr 2007, 6:28 PM
And, by reading the source code, you'll have an even better understanding of how it works than if you'd just referenced something in the docs. :D

Truth is I just don't have time to do that. I need docs that I can quickly reference and that are up to date. This would be one of the first things I would look for when considering using Ext and paying money for a license and support.

All that said, I think what you guys have done so far is brilliant! I guess all I'm saying is that paying customers will expect up to date API docs.

Cheers,

Chris

JeffHowden
2 Apr 2007, 6:51 PM
Truth is I just don't have time to do that. I need docs that I can quickly reference and that are up to date. This would be one of the first things I would look for when considering using Ext and paying money for a license and support.

All that said, I think what you guys have done so far is brilliant! I guess all I'm saying is that paying customers will expect up to date API docs.

I agree completely. The docs will be update to date by release. They just aren't yet as there is still some flux in the development before the final release.

nassaja-rus
2 Apr 2007, 8:27 PM
Why not using wiki for documentation? And place wiki link to top menu?

nassaja-rus
2 Apr 2007, 8:30 PM
And why not use bugtracking with web interface?

brian.moeskau
2 Apr 2007, 8:43 PM
The wiki has been temporarily lost in the move to the new website. It will be back at some point when things settle down. We are working on a bug tracker, but it probably won't debut until after the 1.0 release since that's the focus right now.

jeffiel
2 Apr 2007, 11:10 PM
Hi Ext team,

I'm curious about contributing back to the project... code fixes, documentation, etc. I think you have a willing community here but the avenues are not obvious.

I would be willing to contribute code and documentation that I've needed to create in my development using ext, especially if it helps me communicate with the core developers. It's like trading code/doc contributions for some degree of support.

-jeff

mystix
3 Apr 2007, 12:58 AM
count me in too. let me know when / where / how to sign up :D

KimH
3 Apr 2007, 4:54 AM
I believe that there are many people in here willing to do some kind of documentation and/or creating examples for others to learn from. It is far more productive and would - hopefully - lead to fewer questions in the forums that has already been asked before.

brant
3 Apr 2007, 6:01 AM
I'm curious was the ext documentation generator source ever released? I was going to play with some of the templates and regenerate the documentation for myself.

Wolfgang
3 Apr 2007, 6:05 AM
For some reason, i read so many threads here saying: The docs are not uptodate...

Well, I am pretty sure that the Ext Team is doing their best to:
- work on Ext V1.0 (to get it from alpha to beta(DONE) to Release)
- work on the new Website (Done)
- work on the commercial Part of it (Done)
- work on Documentation (In Progress)
- work on examples (In Progress)

So it does _not_ help anyone, asking the same questions about docs again and again, especially when they are already answered. ;)
When they say the docs will be ready after the Release version is done, than i believe this.

Thats why i really suggest to let the EXT Team continue to do their excellent job. Personally, i appreciate very much their focus on getting the release version done.

However, if one needs docs to go ahread, and walking through the code is not an option, i would suggest to stick with an older version like a 0.33 or 0.4 and go from there.

Again, please keep in mind that V1.0 is not even released.

Just my 2ct

brian.moeskau
7 Apr 2007, 1:45 AM
The main area at the moment where people can contribute is by creating tutorials, They don't have to be overly long or fancy, just useful. See this thread for more details on contributing a tutorial:

http://extjs.com/forum/showthread.php?t=4278

We do plan on resurrecting the wiki at some point as well, and Jack has discussed on another thread his plans for (possibly) making the doc center commentable by the community. Look for more action in those areas post-1.0 release. Believe me, we definitely appreciate the enthusiasm and hope to enable more community involvement as soon as we can.


I'm curious was the ext documentation generator source ever released?

Still no. It's on the list (somewhere) but low priority to get it cleaned up, packaged and made available.

By the way, I've been working on documentation this week, so starting with Beta 2 there actually will be a few new things to read in the docs! ;)