MATLAB Answers

Chad Greene
0

Do FEX users look at Example files?

Asked by Chad Greene
on 5 Mar 2015
Latest activity Edited by Stephen Cobeldick on 26 Apr 2015
Recently I've made a habit of uploading documentation in the form of html example files with my FEX submissions. But I think I used John D'Errico's gridfit for at least a year before I discovered his quite helpful example file. I know to look for example files now, but do casual users of FEX know to click on the little light bulb icon? Do you ever care about example files?

  1 Comment

I'm wondering if a tabbed design of FEX pages might help users find Example files. This would be akin to a Specifications or Reviews tabs on websites that sell consumer electronics.

Sign in to comment.

Tags

4 Answers

Answer by Stephen Cobeldick on 5 Mar 2015
Edited by Stephen Cobeldick on 6 Mar 2015

I have read thousands of questions on this forum, and so far answered several hundred. This gives a little insight into how various users think... and given how many questions on MATLAB Central Answers can be answered by simply referring to the (very first line of the) inbuilt function documentation, it seems that your question "do casual users of FEX know...?" is sometimes going to have to be answered in the negative: if many "causal users" can't even find their way to the first line of the official documentation for the inbuilt functions (which also come at the top of [name-of-search-engine] results), then what is the chance of them finding their way past some little lightbulb icon?
But I would argue that the majority of users find documentation useful: if your functions are well written and well documented, than this will be appreciated by the ones who know, understand and who might find your submissions useful, both learners and experienced alike. The publishing feature is very handy for creating self-documenting examples, and I think it is better to not worry about the lowest-common-denominator, but to keep your focus on providing the best documentation and explanations of your work: this is always appreciated by other users, even the learners and all of those who don't leave a comment.
From my experience I certainly appreciate example files, and like that authors can take little more time (and space) to explain the thinking and requirements for using their submission. And it is always useful to have something to refer to when working with a new function, so I think there is certainly value in these example files.
And of course pretty pictures always helps sell a product!

  3 Comments

If we're choosing who to help, I'd rather help beginners than experts. It's easy to blame beginners for being ignorant and not knowing where to look for help, but it wasn't long ago that I was that beginner. I did not know names of the most basic functions, and it was hard to understand the differences between all the similar-but-not-exactly-the-same functions. At that point, I remember being overwhelmed and confused by the weird language of the same help files that now seem straightforward.
All this to say, I want to do what I can to make coding more accessible to beginners, but given the generally low volume of feedback on FEX, it's hard to know if html example files are beneficial to anyone but the experts, who could just as easily read and understand a function header.
While your statements about looking at the first line of the doc are true, I think we're only seeing a very small non-random sampling of the MATLAB users (of which there are millions).
Here's something that continues to amaze me.
This is the 200th page at 50 files per page sorted by most to least downloads on the FEX. On this page, the files still have 12 downloads in the last month. At the 15000th file, there are still 7-8 downloads per day!
And these don't even count the people like me who will look at the file to see if it's anything that interests me or not before downloading!
My point: There are a lot of people downloading files. So I like your summary, those who download, which is apparently a lot, probably don't mind an example or contents page.
"If we're choosing who to help, I'd rather help beginners than experts": I am not disagreeing with that at all. I certainly am not trying to blame anyone for their lack of knowledge, I merely answered your question by pointing out the fact that even if information is there, it may not come easily to those who need it, no matter how hard ones tries to make it accessible to them. I state this simply as an observation, and that this observation implies that one cannot feel bad about not managing to reach every beginner that you had hoped to.
If you aim to write good code, and supplement it with good documentation then this actually helps people to improve their own code and gives them good examples of what to aim for. Learning something new take many steps, and one of those steps is learning how to search out information to support that learning process, and how to understand the terms and concepts. There is not easy way around this, it simply has to be learned. And when one discovers that little lightbulb icon, a small step has been achieved.
There are plenty of forums and webinars and tutorials online to help people learn the basics of MATLAB, and really it is not the job of every FEX submission to re-introduce simple syntax or language concepts. Instead providing a good example of code and documentation is far more valuable, and is useful for users or all skill-levels. Keep writing your very helpful example files, they help people of every skill level!

Sign in to comment.


Answer by Sean de Wolski
on 5 Mar 2015

Yes.

  4 Comments

Show 1 older comment
repmat('Yes.',3,3) %?
Nice.
Or was it:
repelem('Yes.',1,3)

Sign in to comment.


Answer by Adam
on 5 Mar 2015

I rarely use the FEX, but when I do I only do so for something that is easy and intuitive to understand, otherwise I won't waste my time. Since I have learned a lot of what I know from examples that definitely means FEX submissions with examples are more likely to catch my attention.

  0 Comments

Sign in to comment.


Answer by Wendy Fullam on 15 Apr 2015

This is a related note to highlight that File Exchange examples also appear in MATLAB Examples, alongside of MathWorks-authored documentation examples: This new application is not yet being heavily promoted, but has been designed to optimize the appearance of code examples. Your thoughts and reactions to this new application are welcome - feel free to PM me if you have feedback.

  2 Comments

Looks nice! Bookmarked.
I’d like to see a link to it in the list above the ‘MATLAB Answers’ banner.
Hey neat, I see one of mine in the screenshot. :)
My first reaction is, how do I look at examples related to the Mapping Toolbox? Or climate data analysis?

Sign in to comment.