Thread Subject:

Feedback on New 'Documentation Center' ...

In one succinct phrase, my evaluation is "It sucks"... :(

I don't know what sort of process TMW went through in choosing the
format and content but as a usable and pedagogical tool I can't think it
follows any accepted educational theory.

I've certainly criticized the previous documentation in many ways as
being "too anecdotal" and if anything this is even more so. In
comparison to the previous format (unless there are other features I've
been unable to see/activate) specific complaints I'd make are--

a) No top level TOC that remains viewable to allow to navigate from
where one is w/o returning to the top level page.

b) When you do click on (the who knows what that is?) icon that turns
out to be a TOC it splats it all over the current page instead of a side
frame or even a dockable/movable window to allow one to keep it in view.
  Simply unacceptably bad design... :(

c) No forward/backward links on each page to even allow one to page
through the content w/o manually doing the same navigation back to the
home page or keep having to manually open the above stupid TOC.

d) AFAICT, no index at all.

e) Instead of working to build a coherent exposition of the language
from the basics forward starting w/ syntax and rules from basic
principles, it continues the narrative style but is even more disjointed
than the previous w/ many of the upfront concepts that were in the
previous now seemingly skimmed over entirely.

f) The information content per page is _terribly_ low until one gets
into the function descriptions--there's _way_ too much extra white space
that simply rolls stuff off the screen and takes far too much space for
one or two little examples.

One positive note if there can be anything positive about such a
terrible regression--the 'expand' buttons that initially were
nonfunctional under at least this installation of Firefox do now seem to
have been fixed altho that's a poor trade it's better than when couldn't
even see them...

I think this was a case where somebody designed this for a perceived
modern and/or updated look but missed the boat almost entirely on the
purpose and therefore the content/structure.

--

fyi;

some reviews of 2012b are here

http://www.mathworks.com/matlabcentral/answers/48070-experiences-with-release-2012b

--Nasser

On 10/3/2012 3:10 PM, dpb wrote:
> In one succinct phrase, my evaluation is "It sucks"... :(
>

dpb <none@non.net> wrote in message <k4i643$vfl$1@speranza.aioe.org>...
> In one succinct phrase, my evaluation is "It sucks"... :(

Agree.

Bruno

Hi everyone. I’m the product manager for MathWorks documentation. Thank you for your feedback. I’ve shared your thoughts with the documentation and design team here at MathWorks to help us improve our tooling and presentation.

Given the volume of similar feedback received, we recognize that the table of contents (TOC) design introduced in R2012b does not provide an optimal solution for users who leverage the TOC as a learning tool. Users like you have highlighted the need for a persistent means of orienting themselves as they browse and explore our documentation. Please know that we are working to deliver a more intuitive overall learning experience in future versions of MATLAB.

I welcome you and other users to contact me directly to share additional feedback at wendy.fullam (at) mathworks.com

We also will be offering usability opportunities to help test upcoming changes; let me know if you’d be interested in participating.

dpb <none@non.net> wrote in message <k4i643$vfl$1@speranza.aioe.org>...
> In one succinct phrase, my evaluation is "It sucks"... :(
>
> I don't know what sort of process TMW went through in choosing the
> format and content but as a usable and pedagogical tool I can't think it
> follows any accepted educational theory.
>
> I've certainly criticized the previous documentation in many ways as
> being "too anecdotal" and if anything this is even more so. In
> comparison to the previous format (unless there are other features I've
> been unable to see/activate) specific complaints I'd make are--
>
> a) No top level TOC that remains viewable to allow to navigate from
> where one is w/o returning to the top level page.
>
> b) When you do click on (the who knows what that is?) icon that turns
> out to be a TOC it splats it all over the current page instead of a side
> frame or even a dockable/movable window to allow one to keep it in view.
> Simply unacceptably bad design... :(
>
> c) No forward/backward links on each page to even allow one to page
> through the content w/o manually doing the same navigation back to the
> home page or keep having to manually open the above stupid TOC.
>
> d) AFAICT, no index at all.
>
> e) Instead of working to build a coherent exposition of the language
> from the basics forward starting w/ syntax and rules from basic
> principles, it continues the narrative style but is even more disjointed
> than the previous w/ many of the upfront concepts that were in the
> previous now seemingly skimmed over entirely.
>
> f) The information content per page is _terribly_ low until one gets
> into the function descriptions--there's _way_ too much extra white space
> that simply rolls stuff off the screen and takes far too much space for
> one or two little examples.
>
> One positive note if there can be anything positive about such a
> terrible regression--the 'expand' buttons that initially were
> nonfunctional under at least this installation of Firefox do now seem to
> have been fixed altho that's a poor trade it's better than when couldn't
> even see them...
>
> I think this was a case where somebody designed this for a perceived
> modern and/or updated look but missed the boat almost entirely on the
> purpose and therefore the content/structure.
>
> --
>
>
>
>

On 10/5/2012 12:06 PM, Wendy wrote:
...[please don't top=post; hard follow conversation makes--repaired]...

...

> dpb <none@non.net> wrote in message <k4i643$vfl$1@speranza.aioe.org>...
>> In one succinct phrase, my evaluation is "It sucks"... :(
>>
>> I don't know what sort of process TMW went through in choosing the
>> format and content but as a usable and pedagogical tool I can't think
>> it follows any accepted educational theory.
>>
>> I've certainly criticized the previous documentation in many ways as
>> being "too anecdotal" and if anything this is even more so. In
>> comparison to the previous format (unless there are other features
>> I've been unable to see/activate) specific complaints I'd make are--
>>

...[previous enumeration comments elided for brevity]...

>> I think this was a case where somebody designed this for a perceived
>> modern and/or updated look but missed the boat almost entirely on the
>> purpose and therefore the content/structure.

...

> Hi everyone. I’m the product manager for MathWorks documentation. Thank
> you for your feedback. I’ve shared your thoughts with the documentation
> and design team here at MathWorks to help us improve our tooling and
> presentation.
>
> Given the volume of similar feedback received, we recognize that the
> table of contents (TOC) design introduced in R2012b does not provide an
> optimal solution for users who leverage the TOC as a learning tool.
> Users like you have highlighted the need for a persistent means of
> orienting themselves as they browse and explore our documentation.
> Please know that we are working to deliver a more intuitive overall
> learning experience in future versions of MATLAB.
...

Well, it's nice to know somebody w/ some clout in the proper area at TMW
is reading. The thing is, though, it seems just absolutely
incomprehensible to me that such a blatantly deficient implementation
could have been deemed a viable candidate long before the amount of
effort that must have been expended had been done. Surely _SOMEBODY_ at
TMW evaluated it for actual usability and depth of content and for the
ability to actually pass the needed information along??? Or were they
simply ignored as not being "with the program" and the style over
substance folks were/are running the show? One worries given the
apparent prevalence of such modifications in the actual product release
over fundamental improvements in the product performance and content
itself. Some areas have been complaints for 10+ years and seem to never
get the attention they deserve while the whole interface is redeveloped
for what must have been big bucks at little point other than cosmetic it
would seem...

To continue on my previous note at some additional length--

I think (and have since the first time I used R(3/4???) in the days of
yore and have said innumerable times) the presentation of the
introductory documentation needs to be completely revamped to present
the language as a coherent _language_system_ that starts w/ the rules of
syntax and progresses logically through their application.

I've asked before if TMW has a formal Standard-like document for Matlab
or whether it continues to add features refine behavior more-or-less ad
hoc to fit newer ideas. If, hopefully, the former is so, then sitting
down and translating that to prose more on the style of how many Fortran
(say) vendors' users' and language manuals mimic the implementation of
the Fortran Standard would be imo a worthwhile way to start.

The difficulty w/ the present for new users learning and doing what the
"Getting Started" documentation tries to do is that it is too disjointed
and ad hoc. It is very difficult to generalize from the specific
examples presented as examples when the rules weren't outlined first.

While for experienced programmers it's only frustrating to have to keep
searching until finally find whatever piece it is that are looking for
(which searches made more difficult by the fact that at least up through
my version search doesn't work for single characters like ":" and it's
not at all clear to a newbie that ":" is actually implemented and
documented as "colon" instead of by the colon character).

It's all well and good to have the examples but they should be auxiliary
to the main thread as opposed to trying to carry the burden on their own
as the main thread of exposition.

That's for the newbies; on the other end for the experienced it's the
depth of the definition of what is required behavior by the
implementation that can be counted upon (particularly for edge cases)
that can be the pivotal point. There the exposition of what the
internal Standard says is all important (which, of course, raises the
specter of TMW changing that all too often :( ).

Anyway, one thing at least sorta' positive--I agree the content of the
function section is in general getting better altho I'm not that
thrilled w/ the format chosen at least there is an obvious attempt to
try to improve details therein. It is, however, still a problem in that
owing to the ever increasing number of functions and the very large
number even in early releases it is often a tougher problem to find the
appropriate one than it is to solve the problem one has once one can
find it.

There's where the TOC and a _good_ index (that's more than just a list
of function names but is keyword-generated and cross-referenced as a
reference document should be) and summary tables a la the old text
"HELP" come in to make getting a grasp on what is in the library for
both new and even experienced users possible. Even after some 25(?)
years and using an old version I still occasionally find something I
didn't know about (altho I haven't used Matlab "in anger" now for a
dozen or so after returning to the farm and retiring from active
consulting so it's not like that whole time has been in heavy contact
still it's indicative of the problem of overload everybody faces when
see Matlab the first time).

Hopefully this will provide at least some insight into what I think
would help immeasurably at both ends of the user spectrum...In short, I
think the effort should be expended in content and organization rather
than in changing the format of the presentation--if the content is there
and cross-linked, it could be in plain text w/ a character search engine
and be as informative as the latest flavor-of-the-day splashy web page
design look.

--

On 10/5/2012 1:15 PM, dpb wrote:

> Some areas have been complaints for 10+ years and seem to never
> get the attention they deserve while the whole interface is redeveloped
> for what must have been big bucks at little point other than cosmetic it
> would seem...
>

example: GUIDE has not been updated or improved for many many years.
Same version year after year. Nothing changes in it.

--Nasser

dpb <none@non.net> wrote in message <k4i643$vfl$1@speranza.aioe.org>...

> In one succinct phrase, my evaluation is "It sucks"... :(

I used to be able to easily navigate to the mex interface functions ... one page contained all of the functions in alphabetical order. I can't find this anymore. I can only find subsets scattered on several pages. Is the complete list hiding somewhere? Or just not there anymore?

James Tursa

> > In one succinct phrase, my evaluation is "It sucks"... :(
>
> I used to be able to easily navigate to the mex interface functions ... one page contained all of the functions in alphabetical order. I can't find this anymore. I can only find subsets scattered on several pages. Is the complete list hiding somewhere? Or just not there anymore?

I'd echo this for both the list of properties of UI objects and Simulink S-Function macros.

The tree view previously available was easy to understand, explain and navigate.
With the full list of properties/macros down the left of the page a single click was all that was required to view the specifics of a given property/macro in the right hand panel.

The new approach seems to defy any sort of organizational logic and takes a large number of (wasteful) mouse clicks to navigate.
(And that's just for UI object properties; I'm yet to find a page that shows all S-Function macros listed on the same page -- it might exist, but if it does then it sure is difficult to find.)

It seems that not only has the user interface changed to reflect Microsoft ribbons (not a positive step IMHO) but the doc has moved towards a Microsoft approach too -- that is, difficult to navigate and almost impossible to find what you want even if you know it's there.

Phil.

On 10/5/2012 4:49 PM, Phil Goddard wrote:
>
>> > In one succinct phrase, my evaluation is "It sucks"... :(
>>
>> I used to be able to easily navigate to the mex interface functions
>> ... one page contained all of the functions in alphabetical order. I
>> can't find this anymore. I can only find subsets scattered on several
>> pages. Is the complete list hiding somewhere? Or just not there anymore?
>
> I'd echo this for both the list of properties of UI objects and Simulink
> S-Function macros.
>
> The tree view previously available was easy to understand, explain and
> navigate.
...[while explanation that now isn't elided for brevity]...

I'd add the properties tree of HG objects/properties--it appears the
only path to them is thru various disjointed categories of functions
that eventually leads to the properties but there is no navigable tree
to the full taxonomy afaict...

--

On 10/5/2012 1:15 PM, dpb wrote:
...

> owing to the ever increasing number of functions and the very large
> number even in early releases it is often a tougher problem to find the
> appropriate one than it is to solve the problem one has once one can
> find it.
>
> There's where the TOC and a _good_ index (that's more than just a list
> of function names but is keyword-generated and cross-referenced as a
> reference document should be) and summary tables a la the old text
> "HELP" come in to make getting a grasp on what is in the library for
> both new and even experienced users possible....

Maybe something along the lines of an internal Matlab GAMS a la Netlib
or the (old IMSL/then Visual Numerics/now Rogue Software) IMSL libraries
does...maybe there's another taxonomy that would work better, but the
idea is to make application to specific problems more readily
discernible as to which functions are highest likelihood to help.

This is particularly applicable for certain classes of problems such as
numerical integeration, etc., as one can't get around the fact that many
problems are solved by the clever application of the features of logical
indexing perhaps combined w/ a unique aha! moment of representation,
granted...

--

Hello again,
Just closing the loop on the concerns you've shared regarding the changes shipped in 12b documentation:

In response to customer feedback, MathWorks is deploying an additional 700 redirects for documentation URLs.

When combined with the redirects already deployed (for reference pages, landing pages, installation sections, and release notes), we will be redirecting roughly 70% of R2012a documentation URLs to updated page locations.

We will also continue to monitor "page not found" reports, and establish additional redirects as needed.

Additionally, I'd like to note that the discussion has been incredibly insightful in helping the documentation team establish future direction. Customers noted that the doc appears to have undergone a change in organization and have speculated on the motivation. While SEO was part of our motivation (we think it’s a big step in having URLs provide an indication of page focus), we are also working towards serving up information to support common customer workflows. Our intent is to provide targeted information which meet immediate needs, rather than requiring customers to scroll through lots of information looking for relevant content. I've already noted that your reactions have highlighted the need for contextual tools (such as a persistent TOC) to facilitate this exploration and learning. The changes in content organization, though, have already helped identify gaps in our
information coverage. I want to encourage you all to continue to share experiences and requests for missing information, so our documentation team can continue to expand and improve our content.

As always, please don't hesitate to respond to me directly at wendy.fullam (@) mathworks.com. We'd love for you to participate in either on-sight or virtual usability sessions.

On 10/14/2012 6:58 PM, Wendy wrote:
> Hello again,
> Just closing the loop on the concerns you've shared regarding the changes shipped in 12b
> documentation:
>

I do not have matlab 2012b (have to wait for 2013a since Mathworks
does not make a student version of the 'b' versions for some reason).

But I looked at your new 'DC' here http://www.mathworks.com/help/matlab/index.html

For me, this looks the same as what WRI did with Mathematica help system
starting in version 6. (now Mathematica is at V 8.04).

Before that change, Mathematica had documentation as standard table of
contents, which many also liked. Many people also did not
like the new 'DC' initially in Mathematica. I myself liked the old
help system more.

So what WRI did, is include what is called a 'virtual book' with the new
versions of Mathematica to keep customer happy, which brings back the old
table of content like help system in addition to keeping the new 'DC'.
This way, if someone likes to use the old style, they can.

http://reference.wolfram.com/mathematica/howto/UseTheVirtualBook.html

May be Mathworks can do the same for next version of Matlab? This
way one can choose which one to use? software can be written
to generate the new 'DC' and old style help pages from same content, hence
no need to manually keep these in sync.

> As always, please don't hesitate to respond to me directly
>at wendy.fullam (@) mathworks.com. We'd love for you to participate in
>either on-sight or virtual usability sessions.
>

--Nasser

Hello again,
Just closing the loop on the concerns you've shared regarding the
changes shipped in 12b documentation:
...
... While SEO was part of our motivation ...

What's a "SEO", pray tell???

--

On 10/14/2012 11:35 PM, dpb wrote:
> Hello again,
> Just closing the loop on the concerns you've shared regarding the
> changes shipped in 12b documentation:
> ...
> ... While SEO was part of our motivation ...
>
> What's a "SEO", pray tell???
>
> --
>

my guess is Search Engine Optimization ?

--Nasser

On 10/14/2012 11:59 PM, Nasser M. Abbasi wrote:
> On 10/14/2012 11:35 PM, dpb wrote:
>> Hello again,
>> Just closing the loop on the concerns you've shared regarding the
>> changes shipped in 12b documentation:
>> ...
>> ... While SEO was part of our motivation ...
>>
>> What's a "SEO", pray tell???
>>
>> --
>>
>
> my guess is Search Engine Optimization ?

OK, so we're to Steve L's comment in the other thread of "wrong answer,
but fast", maybe??? :)

I admit I'm still absolutely baffled at how such an initial rollout
could ever have made it through any serious review/comment period. It
seems incredible _somebody_ wouldn't have pointed out the fact that
glitz doesn't replace functionality...

--

"dpb" <none@non.net> wrote in message news:k5g3qi$6u2$1@speranza.aioe.org...
> Hello again,
> Just closing the loop on the concerns you've shared regarding the changes
> shipped in 12b documentation:
> ...
> ... While SEO was part of our motivation ...
>
> What's a "SEO", pray tell???

http://en.wikipedia.org/wiki/Search_engine_optimization

--
Steve Lord
slord@mathworks.com
To contact Technical Support use the Contact Us link on
http://www.mathworks.com

Back in June, using the pre-release, I submitted a thread ID (II0EFD) to the development team on the incredibly outrageous 2012b release. The documentation aspect was one of my major gripes, and the MS wannabee ribbon the other.

As for the documentation, is is absolutely useless to me. My eyes are not so good any more (I have been a user /owner of MATLAB for 21 years...). The font size of the new documentation is not adjustable as is has been in the past, so I am forced to use the 2012a documentation. UNACCEPTABLE under any circumstance.

I can't believe that every user of MATLAB is a 20-something with perfect eyesight.

The light blue on white background is probably the worst choice of font color.

I am seriously considering not paying the annual (for me...) USD 6,000 maintenance fee for this piece of crap software. I do like the new SIMULINK, but the documentation MUST be changed if I am to continue using MATLAB.

How this ever got through the development team is beyond me, considering the feedback they received from the pre-release.

JWB

On 10/20/2012 7:47 AM, John wrote:
>
>
> Back in June, using the pre-release, I submitted a thread ID (II0EFD) to
> the development team on the incredibly outrageous 2012b release. The
> documentation aspect was one of my major gripes, and the MS wannabee
> ribbon the other.
>
> As for the documentation, is is absolutely useless to me. My eyes are
> not so good any more (I have been a user /owner of MATLAB for 21
> years...). The font size of the new documentation is not adjustable as
> is has been in the past, so I am forced to use the 2012a documentation.
> UNACCEPTABLE under any circumstance.
>
> I can't believe that every user of MATLAB is a 20-something with perfect
> eyesight.
...

Indeed, the eyes ain't what they usta' be here, either... :) I've had a
copy of Matlab (not always up-to-date) for since forever it seems, too...

Anyway for font size at least the online version responds to the change
via the Ctrl-+/- keys in Thunderbird browser; not sure how the shipped
version acts. I didn't mess w/ whether could modify color or not; the
blue isn't too bad for me altho that certainly would not be universally
so, indeed...

--

Microsoft visual studio has Ctrl +/- feature.

They do not have ribbon, just the old but well organized menus and a toolbar where the most useful commands needed by the developer can be accessible in a SINGLE click.

Different contexts are accessible by vertical tab, so that the big screen is used to see code and not menus.

The help has table of contents, index table, search feature, examples, and cross links of related topics.
 
TMW needs to hide someone who really know what is an interface design.

Bruno

On 10/20/2012 9:36 AM, Bruno Luong wrote:
...

> TMW needs to hide someone who really know what is an interface design.

I think they did that already, Bruno... :)

"Hire", maybe??? <VBG, gd&r>

--

Oh yeah, hire not hide :-) LOL

Bruno

"Bruno Luong" <b.luong@fogale.findmycountry> wrote in message <k5ue0c$qid$1@newscl01ah.mathworks.com>...
> Oh yeah, hire not hide :-) LOL
>
> Bruno

I agree that the online help for 2012b is horrid. Maybe that's because I'm used to the pane on the left hand side of the screen that allows me to see where I am in the documentation. The lack of context and visual organization is very disappointing.

I went back to the 2012a documentation and hoped that what I was reading hasn't changed in 2012b.