PDA

View Full Version : New Docs



LesJ
16 Jun 2016, 12:28 PM
So, what do you think about the new docs?

The main document tabs are gone, so you will need to rely on your browser tabs.

The new docs app looks a lot cleaner and it's noticeably faster.

Ext JS 6.2 EA (http://docs.sencha.com/extjs/6.2.0-classic/index.html)

Ext JS 6.0.2 (http://docs.sencha.com/extjs/6.0.2-classic/index.html)

hakimio
21 Jun 2016, 12:09 AM
I do appreciate the speed boost, but:

I find it rather annoying that you have to use tab key to select search results instead of arrow keys.
Everything is super-sized now. Might be good if you are using a tablet pc but not desktop like most people do.
I miss colorful icons.
I do not appreciate light gray text on white background.
Barely legible text in the search results saying "alias", "class", "property" should be replaced by icons like it used to be in the old docs.
Edit: also screenshots which now show widgets using classic theme should be replaced with ones which show the same widgets using triton theme. Classic widgets stand-out too much and triton is the default theme now anyway.

llamerr
21 Jun 2016, 3:38 AM
I see big problem with new docs - when I click any link within docs, page is completely reloaded which means blinking and lose of context of what I'm reading and where I am. Tabs or no tabs is not a huge problem for me, but this one is. It would be better if docs used ajax and history api.

Another issue is that upon scrolling docs, anchors are not updated automatically. When I click getProxy (http://docs.sencha.com/extjs/6.0.2-classic/Ext.dd.DragSource.html#method-getProxy) it's updated to http://docs.sencha.com/extjs/6.0.2-classic/Ext.dd.DragSource.html#method-getProxy , but when I simply scroll, few screens down, it's not updating anchor to currently viewed item. I'm not sure if that worked same way with old docs - I think it is, but for some reason it wasn't that big problem (or maybe I'm thinking that because I'm not yet adjusted to no-tabs).

mitchellsimoens
21 Jun 2016, 4:51 AM
I see big problem with new docs - when I click any link within docs, page is completely reloaded which means blinking and lose of context of what I'm reading and where I am. Tabs or no tabs is not a huge problem for me, but this one is. It would be better if docs used ajax and history api.

This is because the docs are static HTML pages, the reason for the speed boost. But as you have found, this also has it's drawbacks like the class tree's state does not persist. One thing I have seen talked about is using something like session storage (or cookies as a fallback) to keep the state but when you open a new tab and switch back and forth which ever is the last used is the one that would be saved (although we could save the state when you click on a class to make sure that one is the saved state).


Another issue is that upon scrolling docs, anchors are not updated automatically. When I click getProxy (http://docs.sencha.com/extjs/6.0.2-classic/Ext.dd.DragSource.html#method-getProxy) it's updated to http://docs.sencha.com/extjs/6.0.2-classic/Ext.dd.DragSource.html#method-getProxy , but when I simply scroll, few screens down, it's not updating anchor to currently viewed item. I'm not sure if that worked same way with old docs - I think it is, but for some reason it wasn't that big problem (or maybe I'm thinking that because I'm not yet adjusted to no-tabs).

The old docs didn't update the hash as you scroll. The issue I see here is when collapsed, each member (config, prop, method, event, etc) isn't that tall (55px is what I see) so as you scroll, how to determine which should update the hash in the URL when you can see several at a time? I could see different users expecting different results with that.

llamerr
21 Jun 2016, 11:59 AM
how to determine which should update the hash in the URL when you can see several at a time? I could see different users expecting different results with that.

I agree on this - I was thinking on keeping the same position when navigating forth and back in the same tab , but there's more than one way to do that.

mitchellsimoens
21 Jun 2016, 12:02 PM
In a single page app or in the current docs? In a single page app there would be a way, cache the class' member on that tab so when you switch tabs you can see if it has a member cached on it's instance and update the hash.

llamerr
21 Jun 2016, 12:13 PM
In single page app. But I guess new docs still would be improved in time?

mlanglois
21 Jun 2016, 1:49 PM
Something so critical to your users actual work perhaps should have been released in a dual launch mode to work out the bugs (of which there are a few).

We're on a development cycle and the bugs in the documentations are getting in the way of looking up things. For example I wanted to get the code for Ext.field.Field.getValue and gave up and just ran grep against the code base.

You should also default "inherited" to on so people get a similar view to what their used to. It's a rare case when the users would want this off.

mhenn
23 Jun 2016, 3:57 AM
Something so critical to your users actual work perhaps should have been released in a dual launch mode to work out the bugs (of which there are a few).

We're on a development cycle and the bugs in the documentations are getting in the way of looking up things. For example I wanted to get the code for Ext.field.Field.getValue and gave up and just ran grep against the code base.

You should also default "inherited" to on so people get a similar view to what their used to. It's a rare case when the users would want this off.

You should still be able to download the old docs for offline use, even if they are not linked anymore. Check this thread for some urls: https://www.sencha.com/forum/showthread.php?301662-5.1.1-apidocs-offline-availability

slemmon
27 Jun 2016, 7:49 AM
Regarding the checkbox for inherited; it was supposed to be checked by default on the first visit, but we discovered some competing logic that set it to unchecked unless you had manually checked it. That bug was fixed today and will be pushed to production soon. May or may not have affected you specifically, but I think that may have caused some confusion for first time visitors to the new docs at times. Sorry about that!

To address @hakimio's points as well:




I find it rather annoying that you have to use tab key to select search results instead of arrow keys.
Arrow key navigation within the search results is being discussed for future enhancement.

Everything is super-sized now. Might be good if you are using a tablet pc but not desktop like most people do.
I'm not sure I follow. Can you be more specific about what you're seeing that seems too large for a desktop interaction?

I miss colorful icons.
Do you mean next to the text of the member-type navigation buttons at the top of the API docs pages? Other?

I do not appreciate light gray text on white background.
Good feedback. We'll take another ergonomics pass at the class member text and try and improve readability.

Barely legible text in the search results saying "alias", "class", "property" should be replaced by icons like it used to be in the old docs.
This is a case of feedback saying "The icons aren't very helpful to me. It would be better to detail the results metadata in text" and "The results metadata in text isn't very helpful to me. It would be better to show the icons." We'll take a look and see if there's a way to try and satisfy both camps and keep the on-screen footprint of the search results tidy.

Thanks again for the feedback!