Sencha Inc. | HTML5 Apps

Blog

A Fresh Approach to JavaScript Documentation—The New Ext JS 4 Documentation Center

August 22, 2011 | Nick Poulden

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 New Ext JS 4 Documentation Center
The redesigned Ext JS 4 Doc Center features Docs, Guides, Videos, and Examples all in one place.

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.

Print view for Sencha Docs
Click to see new print view

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.

h3{clear:both;}. 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

Deprecated, Static and Protected 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:

Inline Examples
The new inline examples lets you edit sample code and see it instantly in a brand new preview mode. Click to see an inline example.

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.

There are 76 responses. Add yours.

Jay Garcia

3 years ago

Great job Nick!!

David Feinberg

3 years ago

This came out great, awesome job Nick and the supporting Sencha crew!

Nom4d3

3 years ago

Thanks for bring us the Tabs back smile
The Inline Examples are awesome!

Just need some CSS fixes for Opera.

koti

3 years ago

guide—> “The Form Package”
link is not working

seifer

3 years ago

Dont load docs by chrome 13

Nick Poulden

3 years ago

@seifer You may have to refresh your cache

Ed Spencer Sencha Employee

3 years ago

@koti works for me…

Steven

3 years ago

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. http://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.

zatmania

3 years ago

Great jobs as usual !

seifer

3 years ago

@Nick Poulden smile thanks

bigfish

3 years ago

Thanks for open sourcing this! I have an idea to use the generated JSON for autocompletion in VIM.

seifer

3 years ago

Tabs works very slow

Loiane Groner

3 years ago

Great job!
And thanks for this wonderful work!

scarsick

3 years ago

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.

Rene Saarsoo

3 years ago

Thanks for feedback @scarsick. We will be working on improving the performance on IE side.

Joel Watson

3 years ago

Nice work, all! I like the new look, especially the distribution of the “section” tabs.

slemmon

3 years ago

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.

Wemerson

3 years ago

Just Wonderfull! Thanks Team!

Joe Kueser

3 years ago

Fantastic stuff.  The best, most robust, most user-friendly online documentation I’ve seen. How long until we see the same for Sencha Touch?

@dmitrybrin

3 years ago

Love the examples and API in one place. Live code editing and preview is brilliant! Good Job team.

Nick Poulden

3 years ago

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

Dowied

3 years ago

Excellent stuff! Nice to see that you guys are listening to the community.
-Dowied

Neil

3 years ago

Brilliant !

Conor Armstrong

3 years ago

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?

Ajsie

3 years ago

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?

Ling

3 years ago

Looks good guys. Renders fine in FF. But not loading in Chrome.

Danguba

3 years ago

Great stuff. Especially return of the tabs and Inline Examples

Rijk van Wel

3 years ago

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!

Sajan

3 years ago

Search box should be on the right side - together with class/object tree.

MrSparks

3 years ago

Great work guys!!! Love the new document system. 

Things are looking up for 4.x framework smile

raivis

3 years ago

@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.

Bernard Cagalj

3 years ago

The tabs are back. Thank you so much!!! smile

raivis

3 years ago

@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)

Thomas Fritz

3 years ago

Great improvement! Really nice work!

zappAtom

3 years ago

Strange, worked at home for me but at work i only see the rotating cogs forever…

zappAtom

3 years ago

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

Ed Spencer Sencha Employee

3 years ago

@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

marko1234

3 years ago

Excellent work guys

koti

3 years ago

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

Reza

3 years ago

So why you do not use Badge for required configs?
:(

Juliano Ribeiro

3 years ago

It was great learning much easier.
Thank you for the efforts.

Maicon Schelter

3 years ago

@Nick Poulden When this new version of JsDuck will be available for Windows version ?

Erico SSJ

3 years ago

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

slemmon

3 years ago

My cursor keep seeking out the search field on the upper-left hand side as well.  Guess that one’s up for debate.

Scott Martin

3 years ago

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.

Loiane Groner

3 years ago

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?

J. Bruni

3 years ago

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. grin

Rene Saarsoo

3 years ago

@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.

J C

3 years ago

Awesome job!  Sencha has grown sooo much this year.  Truly unbelievable.  Keep up the good work!

LoreZyra

3 years ago

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.

seasharp

3 years ago

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.

Leo

3 years ago

This is great!

I’m really happy for this tool…

thank’s

fshort

3 years ago

MUCH better! Nice touch with the inline previews. Well done.

Ajsie

3 years ago

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.

Alain

3 years ago

Really nice stuff coming from the JS fraction @Sencha
I just wish the GXT team was half this good….

Harikumar

3 years ago

Amazing look and neat development.

Pavel

3 years ago

Thanks, much better!

Vishal Kr Singh

3 years ago

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

Nick Poulden

3 years ago

@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.

ValterBorges

3 years ago

Good progress. 

I did notice that in IE9 the tabs don’t close properly by clicking the close it was reloading the tab instead.

ValterBorges

3 years ago

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.

Yousif Atique

3 years ago

Mindblowing and now this is the real wow factor. grin

Paola @ Reed Printers

3 years ago

This is brilliant! will definitely make my work easier! Though I may have issues using it on my IE8 too.

raivis

3 years ago

@Alain
indeed

Paola @ Pickaweb

3 years ago

This is really nice. I cant wait to try this out and see its new functionality. Thanks for sharing this. =)

Shane Avery

3 years ago

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.

Johan van de Merwe

3 years ago

@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.

Paola

3 years ago

this is awesome. I cant wait on trying this out. Hope to see great results with this new feature.

slemmon

3 years ago

BTW, for those who noted it wasn’t working in Chrome I’m seeing it working ok now.

H.W.

3 years ago

I’m curious how was the documentation “print view” implemented?
It would be useful for most ExtJS based apps too.

Thanks in advance.

daiei27

3 years ago

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!

Rene Saarsoo

3 years ago

@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.

H.W.

3 years ago

@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 smile.

Albert

3 years ago

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)

Laptop

3 years ago

cool js beatifull writing good newer looks

Delphia

3 years ago

Why does this have to be the ONLY rliaeble source? Oh well, gj!

Comments are Gravatar enabled. Your email address will not be shown.

Commenting is not available in this channel entry.