Why are all the examples for matlab functions hindered by useless simplistic examples that do not show how all features of the functions work? One cannot determine how to use any function of any complexity with the examples given.

Take a look at any example and forward to me to prove me wrong.

[dpb]

I do tend to agree altho there are some cases that are less bad than others...

I've complained for 30 years that the documentation is all example based and narrative form rather than actually describing the actual language in a formal form as does, say, the Fortran Standard for it.

I understand the intent is for easy learning and getting started at what is supposed to be a rapid development environment but as more and more complex data constructs and exotic functions get added, the complexity continues to compound.

'Tis a conundrum, indeed...

One almost needs two sets of doc's -- one for the beginner/novice/intermediate class of user and another for the advanced or that the beginner can dig into for specific functionality when runs into impasse with accumarray for instance or more esoteric other areas.

Then again, there's the problem that it appears few really do read thoroughly the doc that is there including the examples that often do explain precisely how to solve a problem posed on Answers.

[Guillaume]

My opinion: If I have to look at the examples to understand how to use a function, the formal documentation is not written well enough. And I hate that you have to jump past the examples to look at the actual documentation of inputs/outputs, which is the bit I care about. I agree with dpb, the formal part of the documentation could often use some polish.

On the other hand, I'm probably an atypical users and lots of people do tend to rely on examples to learn how to use functions.

In any case, if you feel that the documentation of a function needs improving, let mathworks know. I've had some moderate success in getting them to improve it.

[John D'Errico]

1. Different people learn differently. Some need examples, and lots of them. Others cannot be bothered to look at a single example. I have gotten many direct e-mail questions that prove that to be true.
2. You will never satisfty all people.

[Rik]

On the other hand, I'm probably an atypical user

You're reading the documentation, I suspect that already makes you atypical.

Writing good documentation is really difficult. You will never cover all use cases without making your doc really bloated. If you have a look at my WBM function (an API to the archive.org Wayback Machine), that doc is already a full page long without a lot of examples. I hope to have answered most questions about syntax, but I'm bound to have forgotten something.

I agree the input/output section can generally use some more detail, especially since that is more geared towards power users.

In general however, I think the documentation is pretty good and much better than many other languages/environments.

Answer 1

[John D'Errico]

As someone who has written dozens of toolboxes, with literally hundreds of functions, and someone who tends to be a manical perfectionist about my own documentation and code...

I'd suggest you are being rather hard. Useless? Really? Seriously? That is just hyperbole.

Simplistic examples? Um, if you don't provide at least some simple examples, then most users will get blown away, having no clue at what the code even does.

Make your examples too complex? Then most users will not bother to read them. Instead, they will just ask innumerable questions on Answers, expecting us to rewrite the MATLAB documentation completely for their personal pleasure.

Is documentation perfect? Of course not. It cannot possibly be saisfactory for every person. As a documentor, you make up examples, you try to cover all use cases you can think of. At some point, you decide that you have done enough, that someone who really wants to use the tool in more depth will be able to make logical extensions of what you have told them already. For example, suppose I was an author of the curve fitting toolbox. (I'm not, but I could have written it, and I wrote my own version of it before the CFT ever existed.)

In the help for fit, I see examples of simple polynomial models. Thus we see 'poly1', 'poly11', 'poly2' as examplary of polynomial models. Surely the user can extrapolate to understand what 'poly5' might indicate. So as a documentor, you go as far as seems reasonable, and then you stop. Otherwise, people will claim you are too wordy. (In fact, I found one user of my toolboxes who claimed that my documentation tends to be TOO extensive. Surely other uses have thought I stopped too soon. How could I possibly win there?)

Now, look at the output of fit.

[mdl,G,O] = fit(rand(100,1),randn(100,1),'poly1')
mdl = 
     Linear model Poly1:
     mdl(x) = p1*x + p2
     Coefficients (with 95% confidence bounds):
       p1 =     -0.5169  (-1.221, 0.1867)
       p2 =      0.1436  (-0.2596, 0.5468)
G = 
  struct with fields:

           sse: 94.558
       rsquare: 0.021226
           dfe: 98
    adjrsquare: 0.011238
          rmse: 0.98228
O = 
  struct with fields:

        numobs: 100
      numparam: 2
     residuals: [100×1 double]
      Jacobian: [100×2 double]
      exitflag: 1
     algorithm: 'QR factorization and solve'
    iterations: 1

So, what might I need to explain there? Most of the return arguments seem self explanatory. G is described as "goodness of fit measures". But at some point, I'd need to stop writing. Do I need to have an in-depth description of what rmse means? Of what an r-squared measure means, or why one might sometimes need an adjusted r-squared measure?

What I see in the help are things like this:

-- SSE sum of squares due to error

-- R2 coefficient of determination or R^2

-- adjustedR2 degree of freedom adjusted R^2

It seems eminently reasonable to me. But the fact is, if someone is wanting to use these tools, without even a clue about empirical mathematical modeling, about regression analysis, they will be completely confused. At the same time, to provide sufficient docs for that (clueless) person to use such a tool, this would require posting a complete statistics textbook in the help.

As far as what you can do with a fitted model, to some extent, you need to understand MATLAB. mdl is seen to be an object, so you need to look at the methods that apply.

>> methods(mdl)

Methods for class cfit:

argnames       coeffnames     dependnames    fitoptions     integrate      numcoeffs      probnames      type           
category       coeffvalues    differentiate  formula        islinear       plot           probvalues     
cfit           confint        feval          indepnames     numargs        predint        setoptions     

Again, most of them seem logically named. But it is required that the user understand MATLAB to get the fullest utility out of the results. To get there, documentation already exists. If you want to differentiate a model, then differentiate seems right. If I have no clue what differentiate means, then I should be taking a basic calc course, and probably not even trying to use MATLAB to do that yet.

So as a writer, you go so far, then you stop. Yes, there is probably some overview of what goes into the docs, but as a proofreader of documentaiton at TMW, they will see what is written, and possibly decide it is sufficient. Will it be sufficient for everyone? OF COURSE NOT! But if they tripled the size of the help, then too many people will feel overwhelmed, not getting through it at all to the important spots. You try to find a happy medium.

As a user, nothing stops you from suggesting documentation patches, additions where you feel the docs were incomplete. I have done so myself in some cases.

[dpb]

I also (at least mostly) agree w/ both Guillaume and John -- I would far prefer the organization be Syntax - Input - Output - Examples so one does get the formal functional definitions first for that comment and that "you can't please everybody and there's only so much that can be documented". Excepting, there can and should be a formal syntax definition that meets the completeness criterion of actually specifying function behavior including edge cases and such. That isn't the manner in which any of the documentation is written.

It is the occasional complex function with many possible uses that aren't at all necessarily obvious from just the syntax for which examples that are teaching tools are particularly helpful.

I may be dense, but when I first saw accumarray lo! those many years ago, I had absolutely no clue how it really worked and even the examples seemed almost magical. I still have difficulty often in actually writing the indexing as I really want; examples of more of the uses could potentially help altho as John notes in consonance with one of my comments, often the users that most need them don't or seemingly won't read them, anyways. (Or, simply their level of programming maturity is such that they're completely over their head as far as comprehension of what the example is showing.)

I also agree that TMW is pretty responsive in making suggested improvements to the documentation--I've had a number of cases arise from Answers Q? to which I've submitted enhancement requests that have been acted upon.

[Rik]

I agree accumarray is a complex function to first understand. I still tend to forget that you have to supply the indices as a merged array.

Thanks everyone, you have motivated me to have a good long look at the doc of accumarray to see if I have a suggestion for a change. It's such a powerful tool that it deserves the best doc it can get.

[John D'Errico]

Accumarray is a good one that can be complicated to figure out. Another is the function sparse, with its two modes of operation, which will surely be confusing to some. And of course, bsxfun might take some thought for some users, especially now that it is becoming almost obsolete. And these are just basic parts of MATLAB, not complicated tools from some tooolbox.

On the other side, I remember spending a fair amount of time explaining to a consulting client how tools like sum, mean, etc., work, in the sense which dimension is acted upon. If you come to the language from a different place where arrays are handled differently, then you can be confused.

I will also admit that there is one significant toolbox that I have never released, because I have never felt it was easy enough to use without a significant amount of reading and direct help from me to use. That even though the toolbox is a tremendously useful one.

[Walter Roberson]

One of the tools I have written has enough options that I feel as if I would have to write a gui before handing it to anyone else...

I haven't even tried to write up comprehensive documentation for it, as I get to feeling that for some of the options, that if the use is not obvious to a person then the use would take too long to explain.

[John D'Errico]

I've always found it somewhat difficult to document gui tools.

[dpb]

Apparently TMW finds that an issue, too... :)

Some of the later apps are mind-bogglingly difficult to wade through the doc's...there's another Q? currently on one of the optimization high-level interfaces that leads to a veritable maze of links with confusingly vague descriptions...

Answer 2

[Steven Lord]

Speaking just from my own perspective, and just giving my opinion:

My understanding of your position is that the documentation should be completely comprehensive, explaining with examples the full use of all the potential options for a function. [I symphathize; often I've asked the developers "What should function X do in situation Y?" But I have an advantage most people don't: direct access to the development staff.] But if we did that, a lot of functions would need to have documentation pages that look more like a chapter from a math textbook. That has benefits and drawbacks.

I remember a lesson from one of the training courses I took here at MathWorks, which I took when I was responsible for part of the new hire training material for new members of the Quality Engineering department. The instructor asked us to whom we should tailor the material in our course: the 25% of the class who knew the material best or the 25% of the class who knew the material the least. The answer was to target the 25% of the class who knew the material the least: if you target the most advanced section of the class you risk leaving behind the people who don't know the material as well. If you target the people who didn't know the material very well, you risk boring the more advanced members of the class -- but you could use them as assistants to help you teach the rest of the class.

Why do I bring up that training? In some sense, the documentation examples are training for how to use the functions. If we made the documentation examples too long and/or involved, new users are likely to TL;DR the whole page.

That being said, in some cases you're right that the documentation should have more in-depth examples. If there's a function for which you wish there was an example covering a specific aspect of that function, let the documentation staff know using the "How useful was this information?" box at the end of the documentation page. Once you vote for 1-5 stars there's an edit box where you can type more in-depth feedback, and I know for a fact that the documentation staff reads that feedback.

Also consider if the example you wish existed is more an example that shows that function in isolation or more of a workflow example that shows how to use that function in conjunction with other functions, or part of a page that discusses a broader topic (like the ODE solvers) rather than a specific function.

Answer 3

[Mark Smith]

I took a rant and dpq was kind enough to respond maturely. I agree entirely with dpq and will continue to wade through the morass of information on Mathworks, the internet and other sources as I find them to get my answers.

Thank you dpq. This question can rest as there is no real answer other than Mathworks knowing all our issues before creating examples. The examples should be more thorough and possible include user input to user questions to specific subjects as part of official documentation.

Again, forgive my rant and thank you dpq.

The moderator can close this issue.

[John D'Errico]

Please don't answer your question with a comment.

[Guillaume]

"The moderator can close this issue."

There are no moderators. Anybody with sufficient reputation can close any question. However, closing a question on Answers make it disappear so it's unlikely that any of us would close this.

Leaving questions open is not an issue.

Answer 4

[Mark Smith]

Many thanks for the inputs. I am not new to coding but new to mallab. I am currently building an app to perform financial analysis using the financial analysis toolkit but am hung up on on basic concepts such as to how global and private variables work with a gui app. In fact, this may not be an issue but I have not asked the question correctly in Mathworks or documentation.

The jsondecode and jsonencode functions should be useful in decoding the json formatted return string from EODHistoricalData.com but it is not clear how they work for an json string of complexity that incorporates ~48k records of 18 columns. Struct2table does seem to work so I have made progress. I suppose that I need to get into the matlab function code behind jsondecode, and other parts of the guts. I accept that this is probably the best approach.

Thank you all for your input. I have used MMA and am now trying Matlab. Matlab is more understandable with respect to syntax and I like the development environment better.

Perhaps I will be able to answer a question with knowledgable response as you have. Thanks

[John D'Errico]

Again, please stop adding new answers. Learn to use comments.

[Mark Smith]

You wrote previously when I posted a comment.

John D'Errico on 20 Jul 2019 at 15:02

Please don't answer your question with a comment.

Please forgive me if I misunderstood that I should have put my previous comment in an answer and any new comment in an answer. I am new to this interchange tool and I sense that I have struck a nerve.

You will not hear further from me. Thanks for your attentiveness to all who have questions.

[Rik]

Every question and every answer has a separate comment section, which helps when the order of answers change (the accepted answer will be at the top, the others are sorted by number of votes, oldest first).

There is no need to stop posting, but it does help if you use the appropriate place to write it. Using this advice increases the usefulness for every future reader (and current readers as well).