PDA

View Full Version : feedback - no tabs?



firefoxSafari
13 Jun 2016, 9:28 AM
Haven't seen the new docs for Ext etc yet, but I think I read that the docs for Sencha Test were similar so I took a look at them.

http://docs.sencha.com/sencha_test/index.html

There are some things I really appreciate such as the improved responsiveness and viewing on mobile devices.

There are a couple things that really stick out to me as working better in the old docs, though. The big one is the lack of tabs. The old docs would open new pages in its own tabbed interface. It was then really easy to switch between them. It looks like this is lost now. For someone who went through the Ext 4.0 launch, it seems history is repeating itself. The initial roll out of the revamped docs for 4.0 didn't include tabs and many people complained loudly. I hope this will be an option, at least on the desktop side.

Also, the transition from a single page app to a set of pages makes maintaining the state on the tree nav much more aggravating. Every folder that you have expanded closes with page refreshes that don't include an element in that folder. For example, if I have future and locator expanded and then click on DataView under future, then the resulting page locator is collapsed again. It might not be a big deal for the relatively small list in Sencha Test, but this could get very tiresome for larger lists.

I like the look and feel, though it's a bit sad to see it's no longer built with Ext. The docs were always a cool example of eating you own dog food that you could point to, an impressive testament to the good things you could build with Ext...

greg.barry
13 Jun 2016, 11:57 AM
firefoxSafari,

Thank you for the feedback!

I knew that the tabs would be a point of contention going into this. Some people love them and some people hate them. We may explore the feasibility of creating tabs within the page, but as of right now, we're hoping that all of the improvements overshadow the tabs being gone.

As for the tree, we may be able to explore adding some state-fullness to the expanded nodes. We have received other internal feedback about that, so it may be something to look into.

Regarding the dog food, as I mentioned in the blog post, we didn't make the decision lightly. Ultimately, I decided that documentation was better displayed as an HTML page than a full application. We are still discussing the possibility of an application in the future.

I've added your feedback to our internal tracking system for potential future inclusion.

Thanks!
Greg

steenole
16 Jun 2016, 12:40 AM
I agree. I like the new look, but usability wise this is a step back. I really miss the possibility to quickly jump between different places in the docs, using the tabs.

One more thing that annoys me: If I search the docs using the search field in the top right corner, it is not possible to use the keyboard to select the desired topic. I am forced to select with the mouse. That slows it down, and is has a bad impact on ergonomics.

greg.barry
16 Jun 2016, 8:34 AM
steenole,

I'm glad to hear that you like the way it looks! I am sorry that you feel it's a step backwards in usability though. We'll keep taking feedback and try to make the experience great for everyone.

Regarding the search accessibility, that's really helpful, thank you! I have added that to our to-do list.

Thanks!
Greg

vadimv
16 Jun 2016, 12:07 PM
Would be great if the old version of docs would support also the latest release, so those who like the tabs can use it. We really like the Tabs, please bring them back :)))

dongryphon
17 Jun 2016, 9:40 AM
Would be great if the old version of docs would support also the latest release, so those who like the tabs can use it. We really like the Tabs, please bring them back :)))

@vadimv

Let me comment on these two things separately:

In-page content tabs
Return to JSDuck (as a means to achieve #1).
We are considering #1 and expected there to be interest in that, but it will have to be an "also does" kind of thing.

We cannot do #2 because there has been a lot of drift between the semantics in the framework and JSDuck. Even though JSDuck in hosted on senchalabs, Sencha does not actively work on JSDuck and so the decision was made to take on our own documentation extractor and presentation layer. This drift has shown up as incorrect documentation which creates confusion for users and difficulty for our developers as they try to appease JSDuck's heuristics.

We are still discussing opening those pieces up for others to use, but we had to start with our own documentation needs.

Thanks for taking the time to evaluate the new docs and post your thoughts. Be sure that we do hear them and are working hard to make the best possible documentation experience. :)

LesJ
18 Jun 2016, 5:12 AM
The big one is the lack of tabs. The old docs would open new pages in its own tabbed interface. It was then really easy to switch between them. It looks like this is lost now.

Can you just use the browser tabs?

Tab switching is slow in Ext JS, so this is probably the key reason why document tabs were removed. The new docs application is now much faster and it's easier to use the search feature.

54712

firefoxSafari
19 Jun 2016, 6:26 AM
Can you just use the browser tabs?

Tab switching is slow in Ext JS, so this is probably the key reason why document tabs were removed. The new docs application is now much faster and it's easier to use the search feature.

Sure, I can use browser tabs. It's not a terrible option, but I still consider it inferior to the old docs app. It wasn't just having tabs, but rather the the interplay between the tree and the tabs the made for a great user experience on the old app. If I have multiple browser tabs, then I have multiple copies of the nav tree and other ui sections in each tab, each of which can have a different state. It's not the same thing.

The search feature is nice and including the guides now is one thing that is definitely better in the new docs and much appreciated.

I don't follow your reasoning on the performance. For the new docs, they copied some basic dom methods into an ExtL namespace, but other than that it's not using Ext and is not a single page app. They made their own lite tree. The performance of tab switching in Ext seems irrelevant since the app isn't using it. They could have made their own lite tabs. I haven't noticed a performance boost from the new docs, either. I inspected the network traffic and profiled JavaScript for the 6.2 docs and the 4.25 docs. The network side is basically a wash. Clicking a link on the tree in the new versus old docs results in a single request of about .1 - .4 s on either, which is fine. Caching headers are sane in both. For the JavaScript, though, the new app was consistently taking several 100 ms more on the same types of pages. It incurs the overhead of rendering the tree and then expanding it on every link click. The new editor / code viewer is also slower to initialize.

Not saying performance is bad or unacceptable, but it's not faster for me. Some of it's understandable; having the code editor be a Fiddle makes perfect sense and it's fine to give a little on performance for it.

One win for both performance and ux would be if they could just make the tree render properly in the first place rather then flashing the screen trying to expand.

mitchellsimoens
19 Jun 2016, 2:14 PM
I wouldn't talk perf on the old jsduck docs. Looking at the source it's doing many things that are not performant and the tabs you see is not actually a tab panel. So the tab switching experience in that app isn't going to be the most performant even on latest browsers there is a lag that wouldn't be there if done today especially with a doxi parser that could create a structure that Ext JS would want natively.

vadimv
20 Jun 2016, 2:20 AM
@dongryphon yes, the documentation correctness should be high priority. Thought we could have a smoother transition.

We can use browser tabs but that would mean to open them in an independent browser window, because usually they tend to be many and don't like to have them mixed with other stuff - so I guess is not a tragedy, will get used to it.

firefoxSafari
20 Jun 2016, 4:22 AM
Not saying the old docs are the gold standard of performance, just that there are some challenges in the new docs due to the decision to move away from an SPA.


...there is a lag that wouldn't be there if done today especially with a doxi parser that could create a structure that Ext JS would want natively.

Now we're talking B) That would be epic and I hope to see it someday!

plnova
20 Jun 2016, 5:27 AM
Where are my tabs? Why did you take away the option for tabs? I love being able to quickly switch to or keep open the items I need to go back and forth or reference the most.

PLEASE GIVE ME BACK MY TABS!!!!

twasink
20 Jun 2016, 9:11 PM
The tabs absolutely have to come back. When you're working with disparate parts of the system (e.g. bouncing between the documentation for a grid panel, a column, and the Table View), the sidebar is insanely inefficient (not least because the tree folders close when you go to a new page).

Using a local copy helps a lot, but it's still nuts. Using browser tabs is a very poor alternative.

Yes, we can use the JSDuck-generated version locally, but then we need to put up with "incorrect documentation"

greg.barry
21 Jun 2016, 8:19 AM
As I mentioned in another thread, I have created this page for folks to download JS Duck up until 6.0.2. Those downloads won't be updated and we won't be adding to the list, but they're there if you want them.

http://docs.sencha.com/misc/guides/offline_docs.html

We'll consider tabs in future iterations of the software.

Thanks for the feedback!
Greg

jvandemerwe
1 Jul 2016, 6:06 AM
First of all I like the new style, but the JSDuck style was also fine to me. But the tabs that are missing is just bad. I have usually quite some tabs open in the API documentation.

Simply when I have the Ext.panel.Panel open and I want to have a quick look at the Tree component, I don't want the Panel to close, because I want to go back to that after looking at the Tree.

Every IDE has a tabs feature where you can have more than 1 source open, so why did Sencha think that this would be different when you use the API documentation. Seems that something was fixed that wasn't broken....

And I am absolutely against having the tabs opened in the browser, because there I have also many tabs open.

So, give me back my tabs.....

jvandemerwe
1 Jul 2016, 6:11 AM
@vadimv

Let me comment on these two things separately:
In-page content tabs
Return to JSDuck (as a means to achieve #1).
We are considering #1 and expected there to be interest in that, but it will have to be an "also does" kind of thing.



Well take a yellow marker and make sure that #1 is marked and gets a high priority and doesn't stay with just considering it.

Scott Murawski
6 Jul 2016, 7:05 AM
+1 for the doc tabs too! As soon as I checked out the new docs, I also felt like it was a step backwards too and didn't make much sense at all. But I guess due to the drift between jsDuck and Ext it was probably easier to not use jsDuck anymore.All together though, I don't think it's specifically the lack of Ext being used, it's just the lack of tabs! Definitely need to get tabs back in there :)

vadimv
8 Jul 2016, 12:58 AM
Lately I've been seeing History Bar in the docs, so that's an alternative solution to the tabs, imo it's ok, thanks Sencha for quick reaction.

firefoxSafari
8 Jul 2016, 1:29 PM
I still like some aspects of the old docs better and believe that a well written single page application would provide a better user experience than several distinct pages.

That being said, the history bar does make the new docs much more usable and I appreciate the quick turnaround on this and the other enhancements in this release.

Chemm
22 Jul 2016, 7:21 AM
How I can generate old-style documentation(fast and with tabs)?

jvandemerwe
22 Jul 2016, 10:16 AM
How I can generate old-style documentation(fast and with tabs)?

As far as I know you can only download the old style (jsduck style) for ExtJS 6.2. You can do that from here: http://docs.sencha.com/misc/guides/offline_docs.html

greg.barry
22 Jul 2016, 10:23 AM
Everyone is still free to use JSDuck:
https://github.com/senchalabs/jsduck

It's still a wonderful docs solution. Our products just started evolving in a way that changed our internal needs.

I'd be happy to help if anyone needs assistance.

Thanks!
Greg