Is online documentation (2023) a terrible idea?

I am probably old fashioned, but separating MATLAB's documentation from the installation seems like a terrible idea. Obviously there is a savings in disk space and initial download, but it assumes perpetual (and consistent) internet access. One of the best arguments for using MATLAB has always been it's tightly integrated documentation. Release 2023a breaks that feature by default.

Mathworks is obviously sensitive to this problem because there is a mechanism for separately downloading the documentation. This will be crucial to anyone that:

1. uses MATLAB without constant Internet access.
2. uses MATLAB behind a corporate firewall. Proxy settings sometimes allow the online documentation to work, but this usually breaks whenever the IT department changes something.
3. uses MATLAB on a standalone (air gapped) machine.

My own work involves all three scenarios. Although the documentation install can be applied in each scenarior, #3 is a real pain.

Is anyone else annoyed by this change?

[Adam Danz]

The steps to take to use local offline documentation that Daniel mentioned can be found here:

• Set MATLAB Preferences
• Installing documentation on offline machines

[dpb]

I hadn't yet realized this having just downloaded R2023a but updating the license and continuing current development tasks with R2020b for continuity until reach a break point.

I think having it default to online may be ok as probably by now a fairly decent majority of users do have a nearly continuous, "fast-enough" connection.

For those of us not in that situation (I've generally got the connection although it isn't terribly reliable as reliability statistics go) but it isn't very fast. The download was seemingly interminable but (fortunately) it did finally complete, BUT, if TMW is going to do this going forward, I'd expect to have been given the option to pick/choose the doc path of choice; just blindly deciding for the user is simply rude.

[Daniel Dolan]

@Adam Danz,

The issue is not that the documentation can't be downloaded separately; that's pretty easy for a computer with permanent or intermittent internent access. The other scenarios are less straightforward, particularly when dealing with colleague who aren't tech savvy or lots of permantly off-network machines. I am also concerned where this is heading, i.e. at some point MATLAB becomes like Python or Julia, where Internet access is almost essential.

Following up on @dpb's point, it seems like local documentation install should be an option when setting up MATLAB in the first place.

[Paul]

Case 3 seems particulary troublesome if trying to keep up with every update of every release.

[Daniel Dolan]

@Paul: updates are also problematic, so I usually stick to specific releases every other year. Unfortunately, some new features aren't fully operational before existing features are deemed obsolete (looking at you, Instrument Control Toolbox), so sometimes standalone machines have to be updated. Separately installed documenation only makes that more of a hassle.

[DGM]

Modularizing a giant package seems like a good thing from this distance, but either way, I'm surprised it's not just an option during installation.

Not that I'm ever going to update again, but I'm curious if the documentation can be obtained on physical media like the installation files can (or used to). If the expectation is that I download a 9GB file using a web browser, then that would never succeed on a connection like mine. I could throw it to cURL and sacrifice my connection for a week, but I doubt anyone else would entertain the idea. Then again, according to the statistics, I don't exist.

On the other hand, I imagine most people rightly never want to have to deal with physical media. I would probably be the only customer, and I've already asserted that I won't be a customer. The question is merely an idle curiosity.

[Rik]

The documentation is such an important part of what makes Matlab great, that I think Mathworks would do well to consider different options. An optional download with only some sections of the documentation would be a large improvement.

[Sarah]

@DGM We do also publish PDFs for folks who need physical media. It would obviously be a LOT of printing but the formatting (chapters, line wrapping, page breaks etc.) are all printing appropriate.

[Rik]

I previously heard it was tricky to find, but now that I try, it is actually fine:

You need to start your journey in the help center:

https://www.mathworks.com/help/index.html

Here you can go to the documentation main page (by clicking 'MATLAB' under the 'Using MATLAB' section):

https://www.mathworks.com/help/matlab/index.html

On this page there is a button called "PDF Documentation":

https://www.mathworks.com/help/pdf_doc/matlab/index.html

On this final page you can find the link to the function reference:

https://www.mathworks.com/help/pdf_doc/matlab/matlab_ref.pdf

[Alexander]

Just to answer on Daniels question: I'm annoyed. And a pdf is no replacement and an internet access either. And @Sarah: Printing the pdf was kidding? Or not?

[DGM]

I was under the impression that the few hundred MB of PDF documentation (which I already collect when relevant) isn't really a substitute for the 9.1GB archive. I'm definitely not going to print anything. I was talking about the practical difficulty in downloading giant monolithic files without setting up tools to manage the download external to a web browser and then dedicating several days (or more) to the task.

When I said "physical media", I meant DVDs. I'm sure documentation on DVD sounds absurd, but was that not where it used to be? That's the only reason I would mention it.

Like I said, I have no stake in this, since I'm never going to actually download the file. Speaking more generally, it just seems like this aspect of accessibility is something that nobody seems to relate to or care about anymore.

[Alexander]

Nobody really seems to care about the accessibility, only the challenge of the actual download process.

[Walter Roberson]

@Alexander

Could you expand on the accessibility issue?

[Paul]

How does this new policy affect examples?

If I'm working witth online documentation, do I still get the Live Scripts for "Featured Examples." I have that now with my locally installed documentation.

Suppose I'm using the online documentation and want to play with some code from the doc page.

It looks like I can still load the 'patients' file, as from splitapply doc page

load patients

but this code from readtable doc page now fails.

filename = 'myCsvTable.dat';
try
T = readtable(filename);
catch
    disp('file not found')
end

file not found

Do I need to download the entire doc if I want to learn how to use readtable (assuming that myCsvTable.dat comes with the doc)? Or does myCsvTable.dat no longer exist and the doc page is just using a bad example?

On my 2021b installation, that file can be found at:

C:\Program Files\MATLAB\R2021b\examples\matlab\data\myCsvTable.dat

patients.mat is here

which('patients.mat')

/MATLAB/toolbox/matlab/demos/patients.mat

Is there distinction between examples and demos?

Answer 1

[Benjamin Thompson]

A lot of people in the defense community work on air gapped networks or computers. When Microsoft changed their Visual Studio documentation to online only it makes it difficult to get questions answered. Hopefully Mathworks will continue to provide a great product in the standalone documentation and not follow the route that Microsoft took.

[Daniel Dolan]

Finally somone appreciates the issue!

Answer 2

[Walter Roberson]

Is it a terrible idea? NO. It works well for many people.

The fraction of people who ask about installing MATLAB for offline use is much smaller than the fraction that install for online use.

For that matter, the fraction of people who ask about installing MATLAB for offline use is notably lower than the fraction that are asking to install without a graphics interface (such as wanting to do a scripted installation for corporate machines.)

Meanwhile, when the online documentation changes, such as better search engine, or a correction or update to a page, the online version reflects the change the very next time the user looks at that documentation.

I for one use MATLAB a lot, and a lot of the time I am googling the documentation anyhow (google has better inclusion / exclusion control.)

In over 30 years of using MATLAB, the number of times I have needed to install it on an offline system has been precisely zero.

(I used to have it installed on a laptop that did not have internet access while I was in flight for a couple of hours, but that was an insignificant portion of the time, and I had full internet access before leaving so I could have easily downloaded the documentation before-hand.)

[dpb]

Other than being totally air-gapped, there are those who don't have the luxury of highspeed and/or reliable internet connections such that having to have a connection to use the doc is also inconvenient at best.

The size of the install has really become a major hassle...the doc is just another one one top. I will only attempt an upgrade about every other year at most; 2023a took several hours; fortunately, it didn't actually drop the connection.

This thing of no restart at some point will likely mean can't get it installed because the connection simply isn't fast/reliable enough.

[Daniel Dolan]

Excellent points dpb. Corporate firewalls are another challenge: even when you have a high-speed connection, you can't always connect to the Mathworks server for installations and updates.

The offline installer forces you to download everything (toolboxes, Simulink, etc.) even when you only need a small fraction of those files.

[Walter Roberson]

So you have identified that users exist for whom this change involves extra work. Does that mean that the change is a "terrible idea" ?

Suppose the change had not been made, but Mathworks added another example to a toolbox that you used. That already takes extra time to download at installation time, which can be a problem for people on slow or metered connections. Does that mean that adding new examples is a "terrible idea" ? Suppose Mathworks adds new functionality, resulting in larger code to download, again presenting problems for people with weak internet connections. Does that make adding new functionality a "terrible idea" ? If Mathworks improves the performance of the Execution Engine at the cost of increasing the code size, resulting in larger downloads, is that a "terrible idea" ? Is there any change that Mathworks could possibly make to its product that increases executable size but which you would not consider a "terrible idea" on the basis that it makes the product more difficult to download?

If Mathworks makes a change that improves the user experience for X% of its users but (in some sense) makes it worse for (100-X)% of the users, then how large does X have to be before you would not consider the change to be "a terrible idea" ? If, due to old equipment or connection reasons or corporate policy, a change improved MATLAB for all but 2 Mathworks customers, but made it somehow "worse" for those 2, then would the change be "a terrible idea" ?

Is the problem that the documentation is no longer bundled with the product, or is the problem that the documentation needs to be loaded in one piece? If the documentation were kept separate but a per-toolbox method of downloading the documentation were provided, would the split still be "a terrible idea" ?

I, for one, have more substantive issues to concern myself with. Like the fact that the new graphics system (uifigure based) is still quite noticably slower and is likely to be for a number of years.

[Daniel Dolan]

@Walter Roberson: Separating the documentation takes away the all-inclusive benefits of MATLAB. There are workarounds for now, but at what point does the product become a scattered collection of parts? What keeps me from switching to Pythone or Julia is that MATLAB just works right out the box.

The specific issues mentioned thus far (standalone machines, poor network access etc.) pertain to the workaround offered by Mathworks for release 2023a. However, I see this a step in the wrong direction. Installations are always going to get larger, but why separate such a core feature?

[Walter Roberson]

@Daniel Dolan

Why separate such a core feature? Because most people do not need built-in documentation, so for most people, the smaller download is a distinct advantage.

Consider for example Microsoft 365, the online-only subscription version of Microsoft Office. It has captured the larger part of the market from installable network-connection-not-needed version of Microsoft Office. Does that fact that there is a fraction of the people who cannot use Microsoft 365 mean that Microsoft 365 is a "terrible idea" ? (I have the real Microsoft Office product because I do not like the subscription model price, not because Microsoft 365 is an online product.)

In my opinion, MATLAB Installer (and Add-On Manager) should offer a tick-box for installing the documentation locally for the chosen products. Sure, make it easy to install documentation locally... no reason it could not be easier than downloading a complete ISO. But IMO that does not mean that switching to defaulting to remote help is a "terrible idea" or "a step in the wrong direction".

[dpb]

I think the code bloat introduced over last number of years is such that it makes the question of "worth it" more of an issue -- the introduction of new, almost identical features with only some minor differences in syntax and parameters/results is, to quote, "a terriblle idea". There are a lot of other areas that yet haven't been touched, why spend the time/effort on those specific areas?

We out here in the hinterlands are fully used to being ignored for services of all kinds; presumption of and reliance upon highspeed internet by vendors is just one example; it's why we have our own electric generation/distribution co-ops; the public and private utilities don't want to serve rural areas because it's not profitable enough. Just a slightly different example of the same phenomenon; vendors do what makes them the best ROI; if they lose a few customers along the way, so be it.

But, whether it is bundled in one package or not, the footprint has gotten to be so large for either that not having a restartable download is a serious shortcoming for those of us not on fiber (and not likely to be any time "real soon now!", COVID/stimulus money not withstanding).

It certainly should be smart enough to only download documentation for the main product/toolboxes for which one has a license, at least as a user option; what's the point in having the doc for something you don't have/

[Paul]

@dpb,

Sometimes I run across some code, often on this forum, that uses a toolbox that I don't have (or have but don't use) and, if my interest is piqued, I'll poke around in the documentation for that toolbox. Maybe I'll learn something and realize I should be using that toolbox. I wonder if anyone has decided to purchase a toolbox license after reading its documentation.

[dpb]

@Paul, that would seem a time/place for the online (although if TMW has followed through with the threat of not letting one have access to even the doc if not a license, that could be an issue), rather than the local copy (unless, of course, you're on the air-gapped machine). Even I can get to the online doc when desire to; it's generally not too bad of an access time.

My main complaint still is the lack of being able to restart failed downloads when it takes multiple hours; I don't have the issue of havng to download and then burn media to sneaker-net it to another machine; just one that isn't always connected and that it is painful at times when is to use.

The pro bono work I've been doing for the local community college foundation has had need just recently to use an online accounting system as an intermediate step in the process of switching from the spreadsheets to a commerical nonprofit accounting system that is cloud based. It has been a real nightmare to try to do things with it owing to the connection bandwidth and reliability. It wouldn't be usable as a production system in my situation; the ladies in the office do have much better connections so it is at least tolerable for them. But, if MATLAB were that way and only that way, I'd have to find something else; it would just be too painful. Fortunately, having retired from the consulting gig, my livelihood is no longer tied in with having MATLAB so it would just be painful, but not livelihood threatening.

Answer 3

[Daniel Dolan]

(This is not an answer, but rather a summary of discussion in the comments.)

Some, and perhaps many, MATLAB users are unaffected by the online default documenation in release 2023a. However, there are several concerns the Mathworks should consider. Not every user has perpetual and reliable Internet access, and the current solution for restoring local documentation does not fully address these problems.

• Distribution bloat is a recurring concern, and there a strong need to be able to resume interrupted downloads.
• Separating the documentation worsens the release/update cycle for offline install. Now I have download an image for update X of 20YY plus the revised documentation for that update. This is now pain for every standalone machine and possibly anyone behind a corporate firewall.

(Now my opinion...)

Documentation is a key selling point for using commercial language like MATLAB. Any friction from not being able to access documentation immediately is an argument for using another language. Convincing a company to pay license fees is not easy. This specific change may not seem like a big deal, but it might be the final straw for someone already fighting against the "Why aren't you using Python/Julia/etc.?". Release 2023a makes that argument a little bit more difficult.

Why not make the decision online/local documentation decision part of the main installer? Presumably there is disk image size limit (maybe Docker related?), but then why not separate MATLAB and Simulink installations?

[Walter Roberson]

(The maximum size of a single file within a .iso is 2 gigabytes -- file sizes are signed 32 bit integers. I see a claim that with some kind of "tricks" that the overall size of a .iso file can reach 8 terabytes. And of course individual files stored in a .iso can be files that have been compressed to 2 gigabytes -- the restriction is not on the size that the compressed file would expand to.)

[Walter Roberson]

I agree that the ability to resume interrupted downloads should be implemented.

[Walter Roberson]

A user who has an unreliable internet connection can access the online documentation before even downloading MATLAB, connection permitting. If connection is not permitting then they probably do not have a connection reliable enough to download MATLAB.

A user who is air-gapped might not be able to access online documentation. However in such cases, the user probably has to go through some corporate IT procedures to ensure that the software is installed in a safe manner, and those take as long as they take -- the difference in installation time between downloading two .iso or three .iso is unlikely to be significant. (Air-gapped systems are not going to be using the online installer, and probably are not using the "download to install later" feature; they are more likely to download the .iso .)

The .iso was already split several releases ago as it no longer fits on a single double-sided double-layer DVD

[DGM]

Maybe this is a bit tangential, but I think we're well beyond the age where fragile package downloaders are acceptable. I've moved terabytes at less than 300kbps, but not with utilities that are incapable of resuming, and not without file integrity checks. I reserve my patience for solutions which actually have plausible potential to work if given time.