Ken & Mike on the MATLAB DesktopOctober 5th, 2009Slimming down the Help browser
If you’re a regular user of the Help browser, you’ll notice that its user interface has changed quite a bit in R2009b. One of our main motivations for these changes was to make the Help browser useful in layouts other than its default layout. Time and time again we’ve seen users struggle to use the Editor and Help browser at the same time, because they both work best when they’re laid out relatively wide. Since users can’t get them both on screen at the same time, they end up switching back and forth between them, wasting time and breaking their flow. If you struggle to see your work and use the Help system at the same time, here are a couple of tips for making the Help browser take up less space in R2009b: Close the Help navigator Yes, really, close the Help navigator (the left side of the Help browser, where the table of contents and the search results show up). It used to be that if you closed the Help navigator you wouldn’t be able to navigate the doc at all - the table of contents, demos, and even the search field would go away with it. In R2009b, we’ve moved the search field up into the toolbar when the Help navigator is closed, and even more significantly, we’ve replaced the old location dropdown with a breadcrumb navigation widget that lets you access to the full table of contents and all of the demos from the toolbar. If you’ve always wanted the Help browser to give more space to the documentation without sacrificing so much functionality, R2009b should be a big improvement for you.  Consider a taller, narrower Help browser Prior to R2009b, it was virtually impossible to use the Help browser once you made it narrow. The Help navigator could only be positioned on the left hand side of the Help browser, and as we discussed above, you lost a ton of functionality if you tried to close it. So if you made the Help browser narrow, you had very little room left to display the documentation. In R2009b, we’ve introduced an alternate layout for the Help browser: if you resize the Help browser so that it’s tall and narrow, the Help navigator moves up above the contents. We’re hoping you’ll find it convenient to try some alternate layouts, like docking the Help browser in a narrow space next to the editor.  Please try out these changes and let us know if they help keep you in your flow - we don’t want you to get bogged down in the Help browser and lose track of your work. We’ll look at some other changes to the Help browser in a later entry. 
13 Responses to “Slimming down the Help browser”Leave a Reply |
|
|||
|
These postings are the author's and don't necessarily represent the opinions of The MathWorks. |
Neet features, but I doubt I will be using them. With the introduction of the F1 quick-help, there is a way to quickly access basic help when coding. If the quick-help is not sufficient, then one must still take a break from coding and focus on the help-files and in that case one wants the optimal layout for reading the help text, which I believe will still be a full-screen help browser.
My 0.02SEK
–DA
Am I the only one who misses the “Index” tab? Why was it removed?
Eric -
How did you use the Index tab?
- scott
When I use my custom toolbox help files, the help navigator does not change focus when linking between help pages from within help pages. How can I force the help navigator to change its focus to the current page? Does that make sense?
Thanks
The new revisions to the help browser are not at all useful to me. I was efficient at using the older version. How can I get it back? If I can’t will you fix this? As far as the question about “how am I using it?”, which was asked in regards to the comment on the index tab - look, developed a procedure that worked quickly for me. I could jump around from index to search and quickly navigate to know sources of information. Y’all went windows vista on me and now I have to, ahem, waste my time and NOT be productive to learn your new help format. Thank you.
I’m with Bryan, I liked the old help browser & the new one has slowed me down.
I use the help all the time & ~90% of the time I’m reading the FRP to code the correct syntax. I’m sure you’ve heard me say it before & I’ll say it again: A FRP should tell me everything I need to know to properly use a MatLab function.
~50% of the time, I navigate to a FRP via the alphabetical list. Most of the rest of the time it is via a “see also” link at the bottom of a related FRP. I suspect this sounds boring to you developers.
Tell me, did you develop this new help format in response to customer requirements? I suspect you didn’t & instead, some sharp developer come up with a really “cool” idea and you guys found this way to use it. e.g., it was a solution in search of a problem.
OysterEngineer,
The Help Browser re-design was based on usability research. It was not the result of a “cool idea”, as you suggest — The MathWorks does not operate that way. Changes to the Help Browser were heavily scrutinized internally before we released the re-design, as we realize how integral this tool is in the work flow of MATLAB users.
What is your biggest complaint with the re-design? The removal of alphabetical list? None of the other items you mentioned (e.g. “see also” links) have changed. I’m curious as to why you think that your description of how you use help “sounds boring” to us developers? We have developers, usability specialists and documentation writers committed to the Help Browser — they live and breathe the nitty gritty details you mention.
It sounds like your particular work flow would be better suited by using Function Hints, the Function Browser and Help on Selection. These tools were designed to let you focus on your MATLAB code without having to shift focus.
-Ken
Good answers & you are asking some good questions.
First, my biggest complaint, starting with some context: Usually, I have the Contents tab on top within the Help Navigator. Or, maybe this is what you call the Function Browser. Anyway, the Help Navigator is always an undocked window so I can use the Windows process to bring the Help Navigator up on top. I’m trying to quickly surf between the appropriate toolbox to find the FRP I’m looking for.
Here is an example work flow, using 2008A. I am forever looking at the FRP for plot & for linespec, usually in that order. So, in the Help Navigator, I navigate to MatLab, Function Reference, Alphabetical List, P and finally plot. After reading what I need there, I find the hot link for linespec and read what I need there. Now, I’m off to my .m file where I do some coding.
A few minutes later, I need to look at another FRP, say tfestimate in the Signal Processing Toolbox. I pop back into the Help Navigator & oops, I can’t see the selection for the Signal Processing Toolbox since the sub-headings under MatLab/Function Reference have expanded. Hey, none of those subheading have ever been helpful to me, so I just collapse them by clicking the - box next to Function Reference. Since I only have 2 levels showing in the Help Navigator, I can now see where I am in the Navigation system. So, I select Signal Processing Toolbox & on like I did a few minutes ago with the MatLab level. I read what I need in the tfestimate FRP and go back to my .m file.
Now, look what happens in 2009B: Of course, the 1st steps thru linespec are the same as in 2008A. But, look at how much more exploded the navigation menu is. I’ve got 3 layers deeper in to separate areas: Mathematics & Graphics. Like I said before, none of those topical sub-levels below Functions have ever been helpful to me. Yes, I can click on functions again and collapse them all. But, they don’t stay collapsed. If next time I go looking for the FRP for class, look what happens, that navigation menu gets even bigger. All the old expansions of the menu keep coming back. So, I’ve developed the habit of clicking all those - boxes to force everything back to the levels 1 & 2 of the menu. That is the process that slows me down with the new Help Navigator & why I like the old one.
Now, after I do this collapsing, I can find the menu selection for Signal Processing Toolbox & I can proceed.
Now you see why I don’t like the new scheme: I can’t keep the help window in the display configuration that is constant and at a level that makes sense for me. I realize that the alphabetical list is still available to me & I use it. But, I dislike having to constantly collapse the extra menu levels that I don’t like or use.
Regarding the Function Hints. When I first read of this feature, I thought it would be helpful. But, it isn’t turning out that way. The latency of the box appearing is too great to make the feature timely. Instead, it is always popping up late to distract me. Many times I purposely write an incomplete line of code because I can’t remember a variable name right now. Or, I want to go review the FRP before finishing the line. So, I want to do some writing on the next line down & instead, there is this box with various suggestions that is in the way. I haven’t figured out how to easily keep from being annoyed by this feature.
I might learn to use Help on Selection. But, the window that pops up is never the size I want & it takes more steps than I like to get it to look proper since it isn’t a normal window. I’ve found that it is better to just stay with the normal Help Navigation pane. I know that no matter what I want in MatLab documentation, I can always get there via the Help Navigator. I know that other options for help are available in the world of MatLab. But, just because they are available, doesn’t mean I find them useful.
Call or e-mail if you want to discuss this more.
OysterEngineer, thank you for the more detailed response (and Ken, thanks for following up before I got a chance to). It’s always great to hear examples from our users about how they interact with the Help browser; we don’t find it boring in the least.
For a little background, we added the extra levels of detail to the table of contents to allow users to navigate directly to reference pages within the contents tree rather than requiring users to navigate partway to the page in the tree and then finish navigating on the “Function Reference” page. This was part of our overall strategy of reducing the number of times that a user has to break their flow while using the Help browser. There are other advantages to having this information in the table of contents, as well. For example, by listing all of the function reference pages in the table of contents you can easily see a list of all of the other functions in the same category in either the table of contents or the breadcrumb navigation. As Ken mentioned, all of these ideas were the result of usability studies.
That said, it does sound like for the scenario you described we’ve inadvertently added some extra clicking into your workflow, which was definitely not our intention. Thank you for bringing it to our attention - we’ll take a close look at that workflow and see what we can do to accommodate it.
Also, I agree with Ken that you might really like the Function Browser. It’s a great addition to the product that was made in R2008b, and it helps you find function reference information quickly. To get started with it, click on the fx icon to the left of the prompt in the command window, type Shift+F1, or select “Function Browser” in the Help menu.
Thanks for explaining the Function Browser. I fired it up and gave it a try. It appears that it has the same index as the normal Help Navigator has under the Functions level. It appears that the Functions level is concatenated from each Toolbox’s Functions level.
So, lets say that I want some information on the eig function. So, I guess that it is under Mathematics & then Arrays and Matrices. Oh, there are 5 more sub-levels. Maybe under Elementary Matrices. No. Maybe under Array Operations. No. Array Manipulation. Maybe I’m at the wrong level. Let’s see, there is Data Analysis. Oops, I think I went up too many levels. Oh, there is Linear Algebra. Oh, it must be there under Eigenvalues etc. Yep, there it is, the eig function.
So, after ~2 dozen meandering clicks, I finally am confident that if I click on eig, I’ll get what I’m looking for. So, I click and a nice attractive window pops up . . . and disappears! Where did it go!? Oh, I see, if I freeze and don’t move my mouse at all, it stays up. It appears to be the FRP for eig, but its like I’m looking at it thru a paper towel tube. No way I can hop back to the Editor to my .m file and type a few characters and glance over to the reference.
You say you got favorable input from usability testing with this? Please, teach me how this can be useful. What is so different about my work flow relative to those who like this?
Not only does this require that the user has a mastery of the indexing scheme for the function topics, but it also requires the user to have an almost photographic memory so you can glance at the fragment of the FRP that he can see while he returns to editing. I’ve been using MatLab for ~40 hours a week for 6 years now & frankly, I gave up on trying to remember the function indexing scheme ~4 years ago. That is why I focus on the alphabetical list. Never more than 4 clicks & I’m reading the FRP.
I know this indexing of a menu has been a challenge for software writers for a couple decades now and it gets more difficult when the total number of menu options exceeds 50 to 100. Think how much more difficult it is in the world of MatLab where just MatLab alone has over 2800 functions!
I see your challenge. And, I recognize that you do need a topical index as well as the alphabetical index. But, since the total number of functions is so large, you really need to make it easy to use some other way to get to the FRP. I gave up and use the alphabetical listing. But, I see that disadvantage since the user must have a good guess about the function’s name.
Yes, it is a challenge to organize functions into categories, especially with so many functions. Ken and I suggested the function browser because is designed to alleviate some of the difficulty of navigating through those deeply-nested categories.
The function browser provides a sort of hybrid approach to navigating the doc that combines the categorical listing with search capabilities. That is, the search results include relevant categories, and you can browse through those categories within the search results listing.
In your example, you might open the Function Browser and type “eigenvalue” into the Function Browser’s search field. This matches one category, “Eigenvalues and Singular Values”, which allows you to bypass the three levels under which that category is nested and jump straight into that category. It also matches a list of individual functions and shows those functions’ summary lines. This list does include eig, so if you want to avoid the categorical listing altogether you can.
It sounds like you are also having some difficulty with the function browser’s user interface. The page that you see is a trimmed down version of the function reference page that focuses on the function’s syntax, since this is most likely to be the user’s biggest need while working in the Editor or Command Window. It shouldn’t disappear just because you move your mouse, unless you move the mouse over another entry in the function browser without moving it towards the reference page window. I know that the function browser’s development team put a lot of work into understanding users’ mouse gestures and doing the appropriate thing, so if you’re finding that the behavior isn’t completely optimal I’m sure they would like to hear about why it doesn’t work for you. If you need the reference page around for longer than just a quick look you can “tear it off” of the function browser using the “grip” at the top of the page. This will allow the page to stick around, floating above the editor or command window, until you dismiss it. Or, if you need more detailed information, the “More Help” link will open the full function reference page in the Help on Selection window. I know that you mentioned that you don’t necessarily like that window. If you’d rather have that link open the Help browser, you can change that behavior in the Help preferences (Type “preferences Help” in the Command Window).
As we mentioned above, feedback on how users actually use our tools is incredibly useful to us. I hope my comments above have been helpful, but if you have more feedback or need any more information don’t hesitate to get in touch with us again.
Hi all,
I’m one of those who almost always used the “index” tab (pre 2009b), and I think I can illuminate one reason.
I, also, find the FRP pages the most useful parts of the help section, and always find myself looking up plot for linespec details.
With the old index system, I’d start typing “plot”. After a few keystrokes, I’d see the FRP I was looking for (I can’t remember if it opened the first entry returned automatically, or if it required one further mouse click to select it).
I understand that there are now two ways to do something similar (search, and quick-help function-browser), but I find them both less-than-ideal.
1. Search.
Firstly, it’s not keystroke responsive (ie, you need to finish your search term and press enter). I found the constantly updating index list helpful in locating a function name I couldn’t quite remember, and I knew straight away if I was on the wrong track. As an example, consider finding the FRP for “regionprops” (which I constantly want to look up). In the old index system, by the time I’d typed “regio”, I’d found what I was looking for. In 2009b search, “region”+Enter returns ROI topics I’m not looking for, “regionprop”+Enter returns nothing, “region props”+Enter returns nothing, “region properties”+Enter returns a large list of various properties (without regionprops in view). I need to specifically hit “regionprops”+Enter to get what I wanted.
This brings me to my second problem using the search results bar. I, for one, really *like* the FRP layout - it’s familiar, and at a glance I can see the syntax required for various usages. When getting to it via a search for “regionprops” however, every instance of the word “regionprops” is highlighted in yellow. I find this distracting, and when looking for different usages of the function, I find myself focusing on the one thing that’s the same between all usages (the word “regionprops”), and not the different syntaxes themselves.
2. Quick-help function browser
I’ve only just started using this (since installing 2009b), so there’s a good chance that I can use it more effectively. I like that I can see what I’m looking for even after typing “regio”. I’m almost never interested in anything under the “Categories” heading - it would be useful to be able to elevate “Functions” higher in the list. However, when I click on the “regionprops” entry, I will reiterate OysterEngineer’s paper towel tube comment. There are 4 uses of regionprops. The small yellow box shows only two of those without scrolling (and in a format/colour not used elsewhere in MATLAB docs). To reiterate a previous point - all instances of the word “regio” in the little yellow box are now highlighted in cyan. Clicking the “More Help…” hyperlink in the corner is a bit better. *This* is what I’d want from a compact function-browser. It has a colour scheme consistent with all MATLAB docs, it has all function syntaxes at the top, and then you can scroll to see descriptions of each syntax below. It’s slightly bigger than the little yellow box, and it doesn’t highlight every instance of words you expect to be plastered all over a page (I know this may be useful elsewhere, but as I said, I find it distracting when viewing an otherwise familiar layout).
So, here’s what I think:
1. Have a version of the function browser as one of the tabs in the main help doc. This version basically works like the old “index” page:
- Results update on each keystroke (when 3+ chars present)
- Clicking a result skips the little yellow box and opens the familiarly formatted FRP pages directly.
- Words are not highlighted (or at least have the option somewhere to turn this off)
2. Have the option to set the first box to pop up from the actual function browser be the “More Info…” style box, rather than the little yellow box.
If user feedback showed that people want to see the short info below each syntax use, then perhaps making each of the lines under the “Syntax” heading hyperlink to that syntax’s info when clicked could be a useful addition.
Well, that’s what I think. I hope it’s useful :)
Cheers,
Sven.
Sven, you’re exactly right that when the index tab went away it took with it the only place in the Help browser where we do an incremental search. We’re planning on doing something about that in R2010a.
As for the highlights, you can remove them by refreshing the page. I know it’s not the most convenient solution, but for now that’s the best we have.
Thanks for the feedback on both the Help browser and the function browser.