Tips & Tricks
Follow


Adam Danz

How to leave feedback for documentation pages

Adam Danz on 28 May 2024
Latest activity Reply by Adam Danz on 30 May 2024

How to leave feedback on a doc page
Leaving feedback is a two-step process. At the bottom of most pages in the MATLAB documentation is a star rating.
Start by selecting a star that best answers the question. After selecting a star rating, an edit box appears where you can offer specific feedback.
When you press "Submit" you'll see the confirmation dialog below. You cannot go back and edit your content, although you can refresh the page to go through that process again.
Tips on leaving feedback
  • Be productive. The reader should clearly understand what action you'd like to see, what was unclear, what you think needs work, or what areas were really helpful.
  • Positive feedback is also helpful. By nature, feedback often focuses on suggestions for changes but it also helps to know what was clear and what worked well.
  • Point to specific areas of the page. This helps the reader to narrow the focus of the page to the area described by your feedback.
What happens to that feedback?
Before working at MathWorks I often left feedback on documentation pages but I never knew what happens after that. One day in 2021 I shared my speculation on the process:
> That feedback is received by MathWorks Gnomes which are never seen nor heard but visit the MathWorks documentation team at night while they are sleeping and whisper selected suggestions into their ears to manipulate their dreams. Occassionally this causes them to wake up with a Eureka moment that leads to changes in the documentation.
I'd like to let you in on the secret which is much less fanciful. Feedback left in the star rating and edit box are collected and periodically reviewed by the doc writers who look for trends on highly trafficked pages and finer grain feedback on less visited pages. Your feedback is important and often results in improvements.

6 Comments

DGM
DGM on 29 May 2024 (Edited on 29 May 2024)
I recently tried to do such a thing, but I wanted to include links and a lot more text than I could cram into a tiny narrow box.
Is there an appropriate/preferred category where documentation (errors specifically) should be reported? I used (if I recall correctly):
Product Usage > Online training or Onramp issues > Errors
Only because that has to do with strictly web content (importantly content independent of any installation). I don't see a clear category for reporting documentation problems via the support interface.
Steven Lord
Steven Lord on 29 May 2024
If what you're reporting is a mistake in the documentation, where it's saying something that's just not correct, I'd report that as a bug.
If instead you want to suggest a way to improve the documentation page, or ask for something that you expected to find that wasn't there to be added, I'd use Enhancement suggestions.
The Description section of the form where you enter the bug report or enhancement suggestions allows up to 3500 characters. If this is something that's been discussed on MATLAB Answers or here on Discussions, including a link to that discussion can save you some characters in that section. Also keep in mind that this form is for the initial submission of the bug report or enhancement request; future discussions with the Technical Support engineer who works on your support case can include a lot more information.
DGM
DGM on 30 May 2024
I'm slowly getting a bit more comfortable with the support interface, so I'm not worried about having a lack of room there. I just didn't want to cast an anonymous short blurb into the abyss via the webdocs feedback form without having any way to make sure I was being understood. I don't think the webdocs feedback events are logged in any way that would allow me to track them.
Adam Danz
Adam Danz on 29 May 2024
Good point! For errors, I would report the issue as @DGM describes.
Contact support > Product Usage
From there, several categories seem appropriate (Errors or performance issues, Report a bug, Enhancement suggestions, Online traiing or Onramp issues). The support specialist who receives your request will know what to do with it.
DGM
DGM on 30 May 2024 (Edited on 30 May 2024)
To be fair, it was a bit of a mixed bag of complaints. Full disclosure, it was about the very old function contrast(), which a forum user asked about recently. The webdocs was plainly wrong in what it stated the acceptable inputs were, but it was also omitting a lot of necessary information. Similarly, the function synopsis was vague and arguably incomplete.
The whole thing boiled down to the fact that this was a very rudimentary and ill-documented function from over 30 years ago, and it probably shouldn't even exist, but compatibility concerns keep it around and sucker unwitting users into trusting that the docs are complete.
So while I was out mostly to get the webdocs corrected, both the webdocs and the function synopsis need attention, and it probably needs a big disclaimer against writing anything new that uses it.
Adam Danz
Adam Danz on 30 May 2024
Thanks for reporting it @DGM

See Also

Tags

No tags entered yet.