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.
5 views (last 30 days)
Show older comments
Take a look at any example and forward to me to prove me wrong.
4 Comments
John D'Errico
on 20 Jul 2019
- 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.
- You will never satisfty all people.
Rik
on 20 Jul 2019
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.
Accepted Answer
John D'Errico
on 20 Jul 2019
Edited: John D'Errico
on 20 Jul 2019
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
dpb
on 21 Jul 2019
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...
More Answers (3)
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
Mark Smith
on 20 Jul 2019
2 Comments
Guillaume
on 20 Jul 2019
"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.
Mark Smith
on 22 Jul 2019
3 Comments
Rik
on 22 Jul 2019
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).
See Also
Categories
Find more on Logical in Help Center and File Exchange
Products
Community Treasure Hunt
Find the treasures in MATLAB Central and discover how the community can help you!
Start Hunting!