MATLAB Answers

1

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.

Asked by Mark Smith on 20 Jul 2019
Latest activity Commented on by Rik
on 22 Jul 2019
Take a look at any example and forward to me to prove me wrong.

  4 Comments

Show 1 older comment
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.
  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.
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.

Sign in to comment.

Products

4 Answers

Answer by John D'Errico
on 20 Jul 2019
Edited by John D'Errico
on 20 Jul 2019
 Accepted Answer

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.

  6 Comments

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.
I've always found it somewhat difficult to document gui tools.
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...

Sign in to comment.


Answer by Steven Lord
on 21 Jul 2019

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.

  0 Comments

Sign in to comment.


Answer by Mark Smith on 20 Jul 2019

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.

  2 Comments

Please don't answer your question with a comment.
"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.

Sign in to comment.


Answer by Mark Smith on 22 Jul 2019

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

  3 Comments

Again, please stop adding new answers. Learn to use comments.
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.
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).

Sign in to comment.