Improve usability by adding descriptions, tooltips, markdown, etc to dashboards and charts

[Ian2012]

Currently, dashboards are shown up without any content other than the dashboard title. We need to improve readability and usability by adding more verbosity anywhere in the superset app

[bmtcril]

Just a note that this should be localized as well.

[felipemontoya]

I think that having a descriptive text "for humans" of what the data in the dashboard says would help a lot.
I've noticed that when I get to superset I end up asking @Ian2012 what the charts mean. Sometimes is obvious, but not everytime.

I thought using the markdown component should be easy but potent enough. I don't know how easy it would be to localize the content of said componenth though.

[sagar-manprax]

I did some research and testing on this. I found out that Superset doesn't allow us to add slice_description in the YAML file that we import.

What I think could be a possible approach to do this is to make changes to the load-xapi-test-data command but that doesn't feel intuitively right.

Any suggestions on how else can we achieve this?

[bmtcril]

I think we can move this forward now. A few notes- we can add fields to the translation script for extraction. I think we should add X and Y labels, as well as chart descriptions to start.

In the chart yaml, when they are set, the following values exist:

slice_name: Grade distribution - courses
description: The distribution of grades for a course, out of 100%. Grades are bucketed
  in ranges of 10%.
...
params:
...
  y_axis_label: Number of Learners
...
  x_axis_label: Grade out of 100%
...

We should be able to mark those fields for translation, for instance here:

tutor-contrib-aspects/scripts/utils.py

Line 65 in ceaf898

strings.append(asset["slice_name"])

We should also expand descriptions by default. We should be able to mark that at the dashboard level by setting:

"expand_slices": {"<slice_id>": true} see here: apache/superset#18347

[pomegranited]

@bmtcril Thanks for showing me the "chart description" text -- I agree that's the best we can do for documenting charts.

But instead of hiding Help links in there, we could put help links/markdown into the dashboards -- this would be more visible, and could be a first port of call for people trying to find out more about the charts in a dashboard?

[bmtcril]

@pomegranited I've been trying to use text on the dashboards sparingly, since there's no way to dismiss it and it will largely be clutter after the first couple of times someone reads it, but I think help links back to Aspects docs for the dashboards / charts would be a great use of that space. There's even a place set aside for that documentation: https://github.com/openedx/openedx-aspects/tree/main/docs/reference

[pomegranited]

@bmtcril That's excellent -- could I tackle building out this documentation and deep-linking to it from the various dashboards and charts?

[bmtcril]

That would be great! There are some thoughts that operators may want to hide those links with a feature flag, but I think we can add that later if need be.

[bmtcril]

I think we can call this done, it will likely need iteration based on user feedback but we have all the tools necessary to make this work really well now 👍