Sencha Inc. | HTML5 Apps

Blog

Doc Center Updates: User Commenting and More

October 21, 2011 | Nick Poulden

We recently blogged about the brand new documentation center created for Ext JS 4. Great documentation is one of the pillars of Ext JS 4 and Sencha Touch 2 so today I’d like to share a few updates we’ve been making to take our docs to the next level.

While we put enormous amounts of effort into our docs, there’s often a snippet of information invaluable to a newcomer or a gotcha that may be missing from the official documentation.

Introducing Documentation Comments

One commonly requested feature of any API documentation is ability to add comments directly to classes. It’s also one of the most challenging features to implement. How do you offer comments when you’re reading the docs locally? How do you handle authentication? How do you make it easy and friendly to use?

So we set out to make adding a comment quick and easy and instantly sharable to the entire Sencha developer community. Today we’re happy to announce the availability of this functionality on the Ext JS 4 and Sencha Touch 2 documentation.

Click to view the Ext JS 4 or Sencha Touch 2 documentation

When you visit the live documentation, the first thing you will notice are comment icons on the API index page. This lets you know how many comments are on both the class introduction and any members within that class (methods, config options, events, etc). Note that comments on parent class members are carried through to child classes. For example, comments on the ‘border’ config option of Ext.AbstractComponent will be shown on sub-classes such as Ext.button.Button.

Individual class documentation pages have a new toolbar icon indicating the number of comments on the main class. You can also see the number of comments on members’ items in the shortcut links that pop up when you hover over member type in the toolbar:

Comments highlighted in new Sencha Documentation

To read comments, scroll down to the comment section at the end of each class intro or class member section and expand the comment box:

Previewing a comment

Comments can be rated by users

We have also included the ability to rate a comment. Each logged in user will be able to vote a comment up or down based on how useful they find the content. Comments with negative ratings will be flagged for removal.

We hope this system will encourage comments of a higher quality. User contributed comments enable experienced developers to offer their valuable insights directly on the API documentation. We hope you share your knowledge!

In order to make a comment, you must be logged in using your Sencha forum account, after which you may post a comment formatted with Markdown. There is a Markdown cheatsheet accessible by clicking the ‘Help’ link while you are posting a comment.

Implementation Challenges

Although we encourage our users to use the live documentation so they always have the most up to date content, many prefer to use the documentation tool locally. In order to support offline comment usage, we enabled CORS support so that authentication and comment posting could be achieved cross domain. If the network is not available locally, commenting is silently disabled to minimise user interruption.

We welcome any comments (!) or feedback you may have regarding additional functionality you would like to see to make our documentation more interactive.

Content Updates

It’s not just new features though, we really care about the content too. When we launched Sencha Touch 2 Developer Preview it shipped with over one hundred thousand words of documentation. And in the last few weeks alone, we’ve added five brand new Ext JS 4 guides:

JS Duck Everywhere

JS Duck now brings API reference, guides, examples, videos and more to one centralized place, making it easy to find learning materials for our frameworks. Over the past week we’ve rolled out JS Duck to all of the frameworks, including Ext JS 3.4 and Sencha Touch 1.1.

Finally, we maintain open threads in the forums dedicated to receiving feedback from you on what we’re doing well and where we can improve. To date we’ve received over 300 replies and I’d like to take this opportunity to thank everyone for taking the time to help us create the best docs we can. We’ve open sourced JS Duck on Sencha Labs, so feel free to fork and contribute with code as well.

As always, we’d love to hear your feedback and ideas in the comments!

There are 28 responses. Add yours.

Mattis

2 years ago

The commenting system sounds really useful!

Jay Garcia

2 years ago

Great job Nick!

David Davis

2 years ago

Great job guys!

Found two issues:
http://docs.sencha.com/ext-js/4-0/#!/api/Ext shows 0 comments, but there are at least 2
When I click sign in, it says no such user

David Davis

2 years ago

Ahh, clicking sign in should probably open and focus the sign in area at the top or have a inline sign in

Conor Armstrong

2 years ago

Fantastic idea.  Really like this one.  This is one of the thing that is great about PHP’s documentation.  Great to see it here in ExtJs & ST

Conor Armstrong

2 years ago

One thing I’ve notice though is people are using the comments to indicate improvements they would like to see to the base code - eg Ext.grid.Panel, method removeListener .  By way of example (not picking on him or anything) @ChristianD comments that he would like a certain return value.

If this type of comment continues, we are going to see lots of somewhat unhelpful comments instead of the more useful code snippets, possible gotchas and tips that are millions of times more useful.  If the Action combo included say “Proposed improvement” as an option, these type of comments could be much more easily filtered.

Loiane

2 years ago

Great Job! Nice feature! smile

Jay Robinson Sencha Employee

2 years ago

Nick, fantastic job on the Documentation app! People are really going to get some use out of these helpful comments. It will help *us* to find the weak areas of the Docs as well!

Vlatko Koudela

2 years ago

As from now I can say that you have the best documentation system! I’ll try to contribute as much as I can.

Jan-Simon Winkelmann

2 years ago

Very nice job, the docs have really come a long way since the release of 4.0 and I’m really happy on how they’re working and performing now. Great work guys!

Henry

2 years ago

Sencha continues to set the bar higher!  This is fantastic!  While I see Condor’s perspective, this happens when commenting is added to any API.  But as the issues are addressed, richer and fuller examples emerge.  I’ve been a part of this community too long to know that there’s a wealth of knowledge waiting for the right medium.  Yes, we have the forums, but having the context of the class/method now is going to help us/me a lot.

Congrats to the docs team!  Keep up the great work.

Ed Spencer Sencha Employee

2 years ago

Thanks @Vlatko and @Jan-Simon smile We are, of course, just getting started. There’s a good deal of stuff in the pipeline that will take the docs to the next level

interfasys

2 years ago

Great news! Adobe has had it for years and it’s very helpful to add code or warn about errors, etc. smile

Les

2 years ago

Good stuff smile

Jay Garcia

2 years ago

@Ed, crap dude.  How much better can the docs app get? :D

JWL

2 years ago

You guys are awesome!

Ed Spencer Sencha Employee

2 years ago

@Jay you’d be surprised wink

Gevik

2 years ago

@Ed,

Could you please clarify (or at least change) the doc on the “Abstract” classes. If these classes are private and we cannot rely on their existence, then how come the components which inherited from these classes still show config options which belong to their abstract parents!

Honestly, as I see it, the abstract classes are here to stay, and will not change as rapidly as stated in the docs.

Not being able to rely on the existence of the Ext.AbstractComponent and its config options for example, will make life for us component developers much harder. Don’t you think?

Ed Spencer Sencha Employee

2 years ago

@Gevik let’s connect after the craziness of SenchaCon is out of the way (we can meet up if you’re coming) smile

Maurice

2 years ago

Will someone verify and check the comments?  Just like with php.net?  I’ve stumpled upon some comments/messages that only said ‘awesome’ (and some reactions to that). IMHO not very helpful!
Just like some questions (how do I do…)
We have several forums for that…
I hope the docs in the packages don’t have this feature wink

So, it CAN be helpful if the content is right. Otherwise: more rubbish and no-one will use it!

Thanks!

Christian Dube

2 years ago

@Conor no hard feelings here, though I should let you know that this comment was from the “beta”. No idea why it wasn’t removed, as I posted several other comments that were removed before going Live.

@Sencha most impressive. This is another great feature that is well implemented.

Nom4d3

2 years ago

Is not working on Opera. It stays on the loading screen forever.

Shaoning Zeng

2 years ago

where can i can find source code? Only app.js in built version i can see.

Rene Saarsoo

2 years ago

@Maurice: The comments will certainly be monitored and cleaned up. It’s already being done.

@Nom4d3: Thanks. Should get fixed soon.

@Shaoning: The source is at https://github.com/senchalabs/jsduck

Kevin Prince

2 years ago

Very Nice. I also really liked the changes to ExtDesigner. Now I want JSDuck in Designer so I won’t have to update generated code.

Anselm McClain

2 years ago

Wanted to say a special thanks for updating the docs on the older frameworks to be duckified.  Much appreciated as I’m in those daily and the new format is much more efficient.

Ed Spencer Sencha Employee

2 years ago

@Anselm that’s great, we really appreciate the feedback. We’ll keep doing that

abc

2 years ago

naslhkjlkakjdsklko irjipruiqejfiqwf qjeipfj jpifjfj jfij fklwjfj

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

Commenting is not available in this channel entry.