At Sencha, we’ve been challenging ourselves to improve our API documentation, and listening to your feedback on what we should focus on. Today, I’d like to share a few of the improvements we’ve made, as well as some of what we’re working on for the future. We hope you like what we’ve done and where we’re headed.
The redesigned Ext JS 4 Doc Center features Docs, Guides, Videos, and Examples all in one place.
Table of Contents
The Return of Tabs
The first thing you’ll notice when you load the docs is that tabs are back — and sexier than ever! While the earlier versions of the docs app had many improvements, tabs were missed by many so today we’re bringing them back by popular demand.
Easy Access to Learning Materials
In addition to the existing API reference and reference guides, we’ve also added easy access to examples, screencasts and other learning materials. The updated docs adds new tabbed sections for examples, guides, and videos. We’ve also revamped and in some cases rewritten the Ext JS 4 guides, improving flow, fixing inaccuracies and bringing them into a new “Guides” section. Now that the examples are part of the docs app, you can play with an example while you’re reading details on the classes that power it.
Another brand new addition to the docs is the videos section. We’re launching with 30 Ext JS videos, ranging from SenchaCon 2010 sessions to screencasts on how to use the framework’s components. We’ll continue to regularly upload more content here, especially in the area of new screencasts explaining many of the framework components such as Windows and Toolbars. All the screencasts and learning materials will also be mirrored on our learning center for those of you who prefer to access materials that way.
We’ve also implemented another of the most requested features, an easy-to-read print view for docs. Click the large printer icon at the top right of a Docs page to preview.
API Reference Upgrades
The new materials aren’t the only improvements we’ve been making: the API reference itself has also benefitted from a lot of hard work. We’ve been through every class in Ext JS to improve the accuracy of the reported types for each of the functions, configs and events, now explicitly stating precisely what types each function or configuration takes.
Badges
We’ve also added badges to all of the functions that are currently Deprecated, Static or Protected, so it’s easy to see if a function is already deprecated. The deprecation notices also point you to the function you should be using instead. The Static functions on each class are separated into their own section so that they’re not confused with normal instance functions.
Inline Examples
Perhaps the biggest upgrade for the class reference pages is the addition of inline examples. We’ve always included code snippets and screenshots in the documentation but before, you had to copy them into your own app to see them work. Now, the new inline examples have a brand new preview mode that allows you to immediately see how sample code looks. Even cooler — you can now edit the example code inline and see your changes live on the page:
The new inline examples lets you edit sample code and see it instantly in a brand new preview mode.
Many of the UI classes already have inline examples and we’ll continue to roll out more.
Powered by Sencha Labs
All of the functionality improvements above are enabled by work on JsDuck, our documentation generator and presentation app. JsDuck is a open source project of Sencha Labs and is hosted on the Sencha Labs github account. JsDuck builds on the standard JSDoc syntax while adding many enhancements to generate excellent documentation for your Ext JS and Sencha Touch projects.
Some of the recent additions to JsDuck include compatibility with Markdown, easy search integration and history/deep linking support. Best of all, the front end app we use on our docs is an Ext JS 4 MVC app and comes included with JsDuck. It’s easy to install for your own projects. Give it a try and let us know what you think.
We’re Just Getting Started
Since the launch of Ext JS 4.0 we’ve been hard at work improving all aspects of helping you learn the framework and build amazing apps. We’ve launched a new learning center, improved the way we track bugs and respond to issues on the forums and more. We’re also working on more screencast videos, more guides and several larger MVC example apps. You’ve given us a tremendous amount of support as well as suggestions on how to improve via the active docs app threads on the forums.
We hope to continuously release documentation updates, so make sure you leave a comment here on on the forum with what you think of the progress and what you want to see next.
What's your reaction?
0
0
Great job Nick!!
This came out great, awesome job Nick and the supporting Sencha crew!
Thanks for bring us the Tabs back :)
The Inline Examples are awesome!
Just need some CSS fixes for Opera.
guide –> “The Form Package”
link is not working
Dont load docs by chrome 13
@seifer You may have to refresh your cache
@koti works for me…
Congrats Nick and Rene! This is really fantastic, and thanks for giving back to the community too!
This is a great forum for those that are interested in following Sencha’s work. https://www.sencha.com/forum/showthread.php?119667-JsDuck-an-alternative-documentation-generator-for-ExtJS
We downloaded JSDuck this morning and we were able to create JS documentation on our project and show the results to our management. They were very impressed. Sencha makes us look like rockstars!
A big thanks from a bunch of fellow geeks.
Great jobs as usual !
@Nick Poulden :) thanks
Thanks for open sourcing this! I have an idea to use the generated JSON for autocompletion in VIM.
Tabs works very slow
Great job!
And thanks for this wonderful work!
Very nice! I really like the new look… @seifer made a valid point tought, tab switching is so slow in IE 8 that it almost makes the doc center unusable. Main left-side tabs aren’t that bad, but switching between center tabs can take more than 4 seconds. The app loads very slowly as well and the gear’s aren’t moving.
Thanks for feedback @scarsick. We will be working on improving the performance on IE side.
Nice work, all! I like the new look, especially the distribution of the “section” tabs.
Looks great on FF 6.0! Not getting past the spinning gears pre-loader on Chrome 14.0.835.94 (beta channel I believe) if that helps.
Just Wonderfull! Thanks Team!
Fantastic stuff. The best, most robust, most user-friendly online documentation I’ve seen. How long until we see the same for Sencha Touch?
Love the examples and API in one place. Live code editing and preview is brilliant! Good Job team.
Thanks for your kind words @joe. We hope to upgrade the existing Ext 3.4 and Sencha Touch 1.1 docs to the new app in the coming weeks. Expect big content improvements for Sencha Touch ready for version 2.0
Excellent stuff! Nice to see that you guys are listening to the community.
-Dowied
Brilliant !
Good work guys.
One thing. The name on the tabs can be ambiguous. Ext.grid.Panel and Ext.form.Panel both show up as just “Panel” in the tabs title bar. Any chance of extending it out if it gives rise to ambiguity with another class?
Great work guys!!
I wonder though, isn’t it better to ditch “Learning center” in favor to the new “Documentation center”? It seems that it is mirroring everything in “Learning center” and has stuff “Learning center” hasn’t.
In that way we don’t have two different places with same materials. Why not put everything in “Documentation center” and have it the same way for all other Sencha products?
Looks good guys. Renders fine in FF. But not loading in Chrome.
Great stuff. Especially return of the tabs and Inline Examples
Wonderful! It’s all looking great, and works fine for me @ Chrome. This is a very good start, and I have no doubt it will only get better in time!
Search box should be on the right side – together with class/object tree.
Great work guys!!! Love the new document system.
Things are looking up for 4.x framework :)
@seifer
Don’t know where u from but tabs are literally flying at my place and I am on the other side of planet than Sencha is.
The tabs are back. Thank you so much!!! :)
@Sajan
Actually that is the left side not the right side. But I disagree, common practice I’ve seen of search boxes is to place them on the top right side. Intuitively I am looking for the search box in top right when I open new UI (regardless if it’s web page or desktop application)
Great improvement! Really nice work!
Strange, worked at home for me but at work i only see the rotating cogs forever…
Gives me 404 Not found errors for
docs.sencha.com/ext-js/4-0/app/view/Viewport.js?_dc=1314088269053
and
docs.sencha.com/ext-js/4-0/app/Application.js?_dc=1314088348146
@zappAtom I had the same, it’s a misconfigured cache. Will try to fix it for next release but for now just force a refresh in your browser
Excellent work guys
Hi All,
It will be nice if you can add link showing list of known bugs in Extjs so that users won’t get frustrated with at least known bugs. And other users wont submit the same bugs.
And also a form to submit bugs as you are asking many details like browser version, os version etc.
Preferably these links should be available on home page like “Report a Bug” & “List of Known Errors” etc
May be you can take a leaf from stakeOverflow, how it helps the users when submitting a question.
koti
So why you do not use Badge for required configs?
:(
It was great learning much easier.
Thank you for the efforts.
@Nick Poulden When this new version of JsDuck will be available for Windows version ?
Google Maps example have a problem with API Key (need to update to new url)
http://docs.sencha.com/ext-js/4-0/#!/example/window/gmap.html
My cursor keep seeking out the search field on the upper-left hand side as well. Guess that one’s up for debate.
I really like the changes. Makes for a nice help interface. I do however dislike all of the dependencies required to install this application. I always feel like I am cluttering my box with extra software I will most likely never use just to generate a help file.
Regards,
Scott.
I have a question: will this new doc be available on the next ext 4 release (I assume it is the 4.1 version) for offline reference?
That’s great. Thanks, Ed, Nick, and everybody else!
I also expect to have the new docs for offline reference, bundled in the next release. :-)
@Reza: There is a badge for required configs. For example: http://docs.sencha.com/ext-js/4-0/#!/api/Ext.panel.Table-cfg-store But not all classes have been updated to have the required members marked up properly.
@Loaine, @Bruni: The new docs version will definitely be included to the next ExtJS release.
@Scott: Are there any other dependencies besides Ruby that are troubling you?
@Maicon: We’re currently working on making the latest JSDuck available for public use, cutting down some needless internal dependencies. Hopefully it will be ready quite soon. Along with a Windows binary.
Awesome job! Sencha has grown sooo much this year. Truly unbelievable. Keep up the good work!
I agree with Ajsie regarding merging the “Learning Center” with the “Document Center.” This is a fantastic idea.
Also koti mentioned that you guys could create a link on the product/download page for a list of known issues (as you do for the Designer). Perhaps you could list a “Changelog” on the download page.
I support koti’s great idea for a submission form of “Report bugs…” This can assist your reports with more concise information as it is defined in the form. Unfortunately, not everyone bothers to read the “How to report a bug” sticky in the forum threads.
Same problem with slow tab switching as reported above. Chrome 13 on XP, 5 year old developer’s desktop. During the slow tab switch I note that CPU goes high. I assume the new help design embeds the whole help navigation tree in each tab?
Since the good old days when the Ext help system was good example of modern browser UI design it has gone from bad to poorly.
This is great!
I’m really happy for this tool…
thank’s
MUCH better! Nice touch with the inline previews. Well done.
The tab feature is appreciated but I find the behavior of opening _all_ clicks in new tabs very disturbing since now I am too busy with closing _a lot_ of tabs.
Can’t you have a right click context menu instead that allows me to open it in a new tab instead?
It’s not always I wanna open something in a new tab.
Really nice stuff coming from the JS fraction @Sencha
I just wish the GXT team was half this good….
Amazing look and neat development.
Thanks, much better!
When do we get the Docs Tabs as one of the components. Autosizing and also the chevron with an awesome menu, highlighting the not visible tabs
@Vishal you can already access the Tab code as JSDuck (the documentation generator) is open source. The Tab component consists of 2 files: a Controller and a View. Check out the code here:
https://github.com/senchalabs/jsduck/blob/master/template/app/controller/Tabs.js
https://github.com/senchalabs/jsduck/blob/master/template/app/view/Tabs.js
Although some of the Tab code is docs specific, it wouldn’t be too difficult to abstract out a more generic version and make it available as a plugin.
Good progress.
I did notice that in IE9 the tabs don’t close properly by clicking the close it was reloading the tab instead.
update.
To simulate the tab problem open developer tools in IE9 and set the IE standards Mode to 7.
The tabs don’t close.
In IE8 mode the animation is choppy but it works.
In IE9 mode it works fine.
Mindblowing and now this is the real wow factor. :-)
This is brilliant! will definitely make my work easier! Though I may have issues using it on my IE8 too.
@Alain
indeed
This is really nice. I cant wait to try this out and see its new functionality. Thanks for sharing this. =)
FYI… I get this error in Chrome’s console: “Uncaught TypeError: Cannot read property ‘id’ of null”. Just spinning gears, no docs. I am using Windows 7, Chrome version 13.0.782.112. IE9, Safari and FF all work as expected on my platform.
@ajsie, I agree, I get a bit nervous from closing all the tabs too. And I don’t want to open them either when I start my doc center.
@Sencha, I do think the doc center is great to work with in general. thanks.
this is awesome. I cant wait on trying this out. Hope to see great results with this new feature.
BTW, for those who noted it wasn’t working in Chrome I’m seeing it working ok now.
I’m curious how was the documentation “print view” implemented?
It would be useful for most ExtJS based apps too.
Thanks in advance.
The new doc system is nice! However, there is still a lot of confusion in terms of best practices for someone trying to learn ExtJS.
I know of a colleague that gave ExtJS a try and hated it because he happened to try one of the tutorials promoting MVC. He just wanted something simple to quickly get his app up and running.
It would be great if there were more tutorials geared towards getting people started, explaining some of the various ways ExtJS can be used (e.g. functional/linear, just OO, and MVC framework), as well as the pros and cons of each.
Also, something covering other basics like creating components in various ways. I know there are docs on xtype/lazy instantiation, etc., but I haven’t seen a whole lot helping someone choose among the various methods. I’ve been refactoring my ExtJS 3.x code and even I have had trouble making some of these decisions so I can understand why my colleague got so frustrated.
Like you guys, I wanna lower the barrier of entry to help get more people onto ExtJS! Thanks for all of your hard work!
@H.W. print view simply displays directly the static HTML-documentation of a class that’s otherwise loaded inside a panel. Not much magic in it.
@Rene Saarsoo Thanks for your answer.
I was hoping that there’s some functionality in (or for) ExtJS4 that would allow to simply transform the Viewport (and all the components in it) into something suitable for printing over more pages :).
Very nice and welcome upgrade. However couple of usability issues:
– performance when switching between the tabs is terrible
– tabs seem to reload the content (the examples)
– the example text editor right click doesn’t seem to work (for copy command)
cool js beatifull writing good newer looks
Why does this have to be the ONLY rliaeble source? Oh well, gj!
Yup it Works Thanks
Thanks for the information your article brings. I see the novelty of your writing, I will share it for everyone to read together. I look forward to reading many articles from you.