Asked by Mark Smith
on 20 Jul 2019

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

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.

Walter Roberson
on 20 Jul 2019

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
on 21 Jul 2019

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

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...

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.

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.

John D'Errico
on 20 Jul 2019

Please don't answer your question with a comment.

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.

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

John D'Errico
on 22 Jul 2019

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

Mark Smith
on 22 Jul 2019

You wrote previously when I posted a comment.

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
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).

Sign in to comment.

Opportunities for recent engineering grads.

Apply Today
## 4 Comments

## dpb (view profile)

## Direct link to this comment

https://uk.mathworks.com/matlabcentral/answers/472624-why-are-all-the-examples-for-matlab-functions-hindered-by-useless-simplistic-examples-that-do-not-s#comment_726488

## Guillaume (view profile)

## Direct link to this comment

https://uk.mathworks.com/matlabcentral/answers/472624-why-are-all-the-examples-for-matlab-functions-hindered-by-useless-simplistic-examples-that-do-not-s#comment_726501

## John D'Errico (view profile)

## Direct link to this comment

https://uk.mathworks.com/matlabcentral/answers/472624-why-are-all-the-examples-for-matlab-functions-hindered-by-useless-simplistic-examples-that-do-not-s#comment_726502

## Rik (view profile)

## Direct link to this comment

https://in.mathworks.com/matlabcentral/answers/472624-why-are-all-the-examples-for-matlab-functions-hindered-by-useless-simplistic-examples-that-do-not-s#comment_726518

Sign in to comment.