Will Quality of Documentation be better in 2024 Products?
George Carlisle
on 13 Mar 2024
Latest activity Reply by George Carlisle
on 16 Mar 2024
Mathworks has always had quality documentation but in 2023, the documentation quality fell. Will this improve in 2024?
12 Comments
Time Descending
Note: I would not be surprised if this question is transferred to a discussion. In fact, I am considering doing exactly that myself, as this is not a question that is appropriate for Answers. If so, the appropriate forum would be discussions/general.
If there is something specific that you think was lacking, then it is your responsibility to tell TMW what was missing. Don't just post some random rant about how the documentation has decreased. We cannot possibly know what it is that you think is poor. So that is all you have done, is make a random rant.
I'm sorry, but the onus is on you to tell TMW where you see something lacking. Are the authors of the docs perfect? Of course not! Everybody has an occasional blind spot.
But you can help to improve things, instead of just complain. Be positive. Be constructive. AND, contact the right people, via the proper channel. Answers is not that. One thing I have always seen are quick responses to the support questions I have sent into tech support. And given that your issues seem to be with perceived flaws in one or more docs, any appropriate fix should be almost trivial, at least if you carefully explain what was lacking. Again, Answers is not tech support.
(And, yes, I am sure you will decide to flag my response as a troll, as you did with the response from Walter.)
As I expected from you based on your responses elsewhere, I got sworn at. There was no reason for you to do that, so I removed your curse.
And, YES, if you perceive a problem, then it is your responsibility, OR live with what they give you. You can either help to improve the product, or just be a troll. As I suggested, Try being constructive. You might make the world just a tiny bit the better place if you do.
So it's my job now to tell Mathworks how to do documentation?
No, it will not improve in R2024a.
Release R2024a has not been released yet. As such we can't answer questions about it.
But I am curious about your first sentence. You said "the documentation quality feel." Feel what? Is there some specific feedback about your experience with the documentation in release R2023a or R2023b that you want to share? Is it with the documentation in general, a specific product's documentation, or a specific documentation page?
If the last of those, navigate to the documentation page online (like the documentation page for the sin function as an example), scroll to the end of the page, and give it a star rating. Once you've rated it you will be given the opportunity to provide some text feedback on the page. This information gets sent to the Documentation staff for review and consideration.
(It looks like GSG is Getting Started Guide, UG is Users Guide, IG I am not sure of, REF is probably Reference, RN I am not sure of.)
The message was edited to now say "fell". But I would still be interested in more information about what specific qualities of the documentation the poster feels decreased in quality in release R2023a and/or R2023b.
I meant "Fell"
I'll post examples later but I'll state this off the top now
- File labeling is poor and inconsistent.
- Some sections are incomplete. I've downloaded toolboxes documentations in the past and all had the same format (GSG, UG, IG, REF, RN) but now all sections are not standardized. Some are missing references or IG.
- Also, why not expose the GSG guides for these toolboxes(DO Qual, IEC & PolyTest)?
For your first point, which files? Are you referring to one or more of the examples, are you referring to sample data files used on some of the documentation pages like how this documentation page uses airlinesmall.csv while this one uses patients.xml? Or are you referring to the names of the documentation page HTML files themselves? Or the fact that some functions in our products have names that are short words (like clear, ones, etc.) and others are longer (griddedInterpolant as one example)?
For your second point, are you referring to the sets of PDF documentation? I'm doing a quick scan through some of the products and the ones I've checked all seem to have a User's Guide and Release notes. Many also have a Getting Started guide and a Reference, but not all. If there is a product that used to have a Reference PDF but does not have one any more, could you state which one or ones you used to use? I don't know for certain why a product would no longer have such a reference: maybe if it was big (the MATLAB function reference PDF is up to 18,646 pages and almost 100 MB in release R2023b) and we found no one was accessing it, to save space we may have discontinued it?
I'm not sure what IG stands for. Installation Guide, perhaps? If that's the case there's one main installation guide for the products that use the main MathWorks installer, in the Installation and Licensing documentation linked as "Installation Help" under Resources on the main documentation page. A quick check found that Polyspace Access also has an Installation Guide, I believe this is because it uses a different installer. I haven't searched extensively to find which other products (if any) have an installation guide.
For your third point, taking DO Qualification Kit (for DO-178) as an example, you were expecting to find a PDF version of the Getting Started category in the documentation? I don't see a separate PDF with just those sections, but all of the headings in that category seem to be present in the DO Qualification Kit User's Guide PDF file based on its Table of Contents. I'm not certain why there isn't a separate PDF but perhaps the documentation staff thought the material would be more easily understandable in context in the main documentation PDF instead?
Looking back at older releases (specifically release R2018b, the oldest release whose documentation is available on the website) I see that there are two other PDF files in that doc that are not present in the release R2023b documentation. I'm not familiar at all with this product but skimming through the first section of the R2018b PDF file it looks like there are a lot of references in the first section of the qualkitdo_do178_workflow.pdf file to documentation for other products. Perhaps in the releases between R2018b and today that information was reorganized (due to features introduced in the intervening releases, due to feedback from users, due to feedback from internal reviewers of the documentation) and so those two other PDF files are no longer needed as standalone books.
I still recommend that if there is a particular documentation page or section where you believe the documentation got worse or could be improved, use the star voting at the end of the page and then provide free text feedback. I know (through conversations with documentation managers in my area) that they read that feedback. The pages where you can access the PDF documentation don't offer the option of rating, but in that case I'd use the product's main documentation page (like this one for Global Optimization Toolbox) and just write that the feedback is about the PDFs.
Maybe George meant "fell". Or maybe he meant "feels worse". Wouldn't that be ironic - a typo or missed word in a post complaining about poor documentation?
We would need specific instances of how the documentation is worse than before. I find the documentation stays the same when it needs to but sometimes they improve some pages based on new features being added or deprecated, or based on user feedback (yes, they actually do read the comments you type in after you give the star rating at the bottom of the documentation page).
I’ll reply when 2024 comes. I think talking about this now is unproductive. My comments weren’t meant to be offensive but I can imagine a huge product portfolio of documentation is hard to maintain. In the past, MathWorks documentation was so exacting that I had no reason to consider other products. Recently, I looked at Mathematica’s products and returned to 2023b and just noticed the differences but we’ll talk again at 2024
Sign in to participate
