Doc Center Updates: User Commenting and More
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.
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:
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:
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.
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.
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:
- Keyboard Navigation
- Mapping a Grid to a MySQL table using Direct and PHP Part 1 and Part 2
- CRUD with an Editable Grid backed by Node.js and MongoDB
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!