What are Your Thoughts on TMW Documentation Linking to the File Exchange

Kind of similar to this Question, I noticed that the Tips section of integral3 cites this File Exchange submission as an option to evaluate higher order integrals. I appreciate the tip, but it seems like that's not how the doc should work. Thoughts?

[Walter Roberson]

I am not clear what your objection is?

• the documentation should have included complete code instead of linking to a source for the code?
• the documentation should only link to Mathworks-supplied contributions, not third-party contributions?
• if it is important enough to be worth linking to a FEX contribution, Mathworks should have made it a distinct command ?

[Paul]

Basically the second bullet. It just seems peculiar to me that the TMW would link to third party software. Does TMW stand behind such third party software as it does its own?

Are you aware of any other FEX submissions linked from the doc?

[Image Analyst]

Um, you do know that that File Exchange submission referred to was created by Mathworks staff, not some arbitrary person in the general public, right? So I'm not sure I would call it "third party" software. There is a great number of File Exchange submissions uploaded by Mathworks staff members.

[Walter Roberson]

Some portions of MATLAB (for example licensing problems) and some portions of the help documentation now link to MATLAB Answers questions, despite the fact that those questions might get deleted or editted to say something different. This is sometimes a bit of a nuisance, but it is not more of a nuisance than the fact that even some Answers supplied by Mathworks in official Mathworks Support questions sometimes link to material that Mathworks later removes. Links into specific portions of help documentation that are given those long alphanumeric tags are especially vulnerable: those tags coulld potentially get completely changed with each different MATLAB release.

Link-rot is a problem. The Stack Overflow way of dealing with it is to require that the relevant portions of documentation are copied into the post... even if the relevant portions is somewhat long. For a couple of reasons, I would be opposed to MATLAB Answers having a similar policy.

[Paul]

@Image Analyst

Yes, I do know that the linked example was created by TMW staff. Whether or not that should be considered "third party" software depends, IMO, on TMW policy for staff submissions to FEX. I added a comment in this regard to your answer below.

[Mike Hosea]

Perhaps the tip in question

• To solve 4-D and higher order integrals, you can nest calls to integral, integral2, and integral3. Another option is to use the integralN function on the MATLAB® File Exchange, which solves integrals of orders 4 - 6.

could be reworded a little to cast the reference to the FEX in a different light than it was received in this case. You can use integralN as a black box without understanding how it works, but it actually is an implementation nesting integral, integral2, and integral3 as articulated in the first sentence of the tip. I literally wrote it because writing it was easier than explaining how to nest calls.

When seen as a black box for higher dimensional integration, it is only a brute-force approach. The help text at the top of integralN explains as much. I didn't try to get it adopted into MATLAB because I think MATLAB should implement something more efficient.

Answer 1

[Walter Roberson]

I have no problem with Mathworks documentation pointing to FEX contributions, even third-party FEX contributions.

This may be because I do not consider the role of documentation to be master records of pristine Definition of the product, in which every word must be TRVTH from on high. I have seen enough sterile Just The Facts Java documentation to know that style is frustrating and of low value for most people.

I consider the role of documentation to be more to help the users get things done.

Mathworks documentation is generally valuable because it explains and gives examples. If someone on the documentation staff wants to say, "You could learn something by looking at this particular File Exchange Contribution, which applies these principles", then that is completely fine with me.

If, though, Mathworks were to neglect its own efforts and just say, "Shrug, poke around the File Exchange, maybe you'll pick something up somewhere", then Yes, that would be a problem. But that isn't the problem being discussed, and I would be disappointed if this all turns out to be a Slipperly Slope argument.

[Image Analyst]

Do other major publishers (e.g. Microsoft, Oracle, Adobe, HP, Dell, SAP, etc.) have documentation pointing to third party web sites?

[Walter Roberson]

I have seen sites point to Microsot documentation. I have seen other sites point to Wolfram Alpha (for definitions of mathematical functions)

[Walter Roberson]

https://www.mathworks.com/help//simscape/lang/scatteredlookup.html is an example of a Mathworks documentation page that points to wikipedia

https://learn.microsoft.com/en-us/javascript/api/%40azure/service-bus/topicproperties?view=azure-node-latest is an example of a Microsoft site that points to wikipedia .

https://docs.oracle.com/cd/E19316-01/821-1857/gkepn/index.html is an example of an oracle page that points to wikipedia.

[Walter Roberson]

https://www.dell.com/support/kbdoc/en-ca/000192205/how-to-identify-sparse-files-on-isilon-powerscale dell -> Wikipedia

Answer 2

[Image Analyst]

I think that as long as the documentation refers to other Mathworks staff-supplied web pages or code, it's fine by me.

[Paul]

Would it be obejctionable if the doc linked to a FEX submission by someone that's not TMW staff?

[Image Analyst]

To me, yes. I don't mind if staff mentions File Exchange entries in blogs or Answers posts but I don't think unvetted, open source code should be recommended in the official documentation.

[Paul]

I'd like to pull the string on this "unvetted" thought. Do you have reason to believe that the TMW actively vets FEX submissions by TMW staff and/or has corporate policies in place that limit which staff can submit to FEX? In other words, why would you put more faith in a FEX submission with a Staff flair than one without (assuming you didn't recognize the name with the Staff flair)?

To be clear, I have no reason to doubt that the example FEX submission I linked is high quality. It's had lots of downloads and all of the reviews are positive.

[Walter Roberson]

I have seen some low quality FEX contributions from Staff. I have also seen some low quality Answers from staff. I have seen Staff suggest third party FEX contributions in Answers

[Paul]

I don't take Staff inputs on Answers as being made on behalf of TMW, so I have no issue with Staff suggesting FEX contributions on Answers. Your opinion on low quality Staff contributions to FEX suggests that TMW has no role in, and takes no position on, those contributions. If so, I'm kind of suprised that there is no disclaimer to that effect on the FEX front page or About page (at least not that I could find with a quick check).

[Walter Roberson]

Mathworks does not consider a disclaimer needed on the FEX page about staff contributions because the only "official" contributions are those marked as author Mathworks Support or one of the various Hardware Support teams or one of the assorted Contest teams. The contributions from individuals marked Staff are considered to be individual contributions from people who "just happen" to work at Mathworks.