Cube Query Rendering - Document available visualization options

Problem to solve

Customers would find it helpful to know how visualizations can be configured.

We've built several visualizations, each type should be documented along with the options that can be defined and used to customize the visualization.

Proposal

1. Update the documentation

Implementation plan

Add a section to the Product Analytics user documentation that:

• Link to the ECharts documented options available for chart visualizations.
• Shows the available options for SingleStat type visualizations. Currently just decimalPlaces: Number, default 0.
• Explains there are no options available for DataTable type visualizations.
• Provides an example of a typical chart visualizations options object as seen below.

  "options": {
    "xAxis": {
      "name": "Time",
      "type": "time"
    },
    "yAxis": {
      "name": "Counts",
      "type": "time"
    }
  }

added to epic &8525 (closed)

changed title from Cube Query Rendering - Document visualisation options and to schema to Cube Query Rendering - Document visualization options and to schema

changed the description

added documentation groupproduct analytics typefeature workflowplanning breakdown labels

added devopsanalyze sectionanalytics labels

changed title from Cube Query Rendering - Document visualization options and to schema to Cube Query Rendering - Document visualization options and add them to the schema

mentioned in merge request !105291 (merged)

My suggestion would be to maybe wait until the first big batch of visualizations + dashboards are done, as I am expecting multiple things being added or removed during that time until we use them fully.

Totally agree 💯. I've provisionally added this to the customer preview because I believe by then we'd have a more defined picture.

Setting label(s) ~"Category:Product Analytics" based on groupproduct analytics.

added Category:Product Analytics Visualization label

changed epic to &9899 (closed)

changed milestone to %15.11

@lciutacu @jiaan @jheimbuck_gl we have 3 visualization types now, is it worth starting this in %15.11?

@stkerr thanks for checking in on this issue! Yes I think it would be good to have. 👍 For full transparency there are still some ongoing changes & discussions to the configuration schemas, for example Product analytics - Designer outputs incorrect ... (#390707 - closed), but I think it's fine to document what we've decided on now and iterate from there.

I think its too early to invest that time as we are in the next step will have panels from components like the ones in optimize and same goes for all data query options like limits, filters etc.. I would rather see the same time be invested in a bigger focus on making it an 100% editable experience with more options rather a code first approach which is done through the files.

@timzallmann @jheimbuck_gl @jiaan I think additional features is a bit of an orthogonal issue, since this is Technical Writing that doesn't come at the expense of development.(If this issue requires frontend/backend development I'd tend to agree with you though. Let me know if there is development work attached to this) Especially when we are loading user-written dashboards from the backend, users will need good docs on how to write & debug those files.

@stkerr This is not just technical writing. Updating the schema especially will be direct discussion and also development work involving FE + BE engineers. This needs specs, tests and so on. Even the first iteration took a lot of time of IC's.

Biggest question for me is that we are not that far off to have everything anyhow editable directly in dashboards and visualization designer so there is no primary need for actually learning and editing dashboard files.

Just recent feedback + adoption rate in some other new areas showed that having a hurdle of configuration (which yml files are) is a huge show stopper for adoption.

@timzallmann @stkerr @jiaan

Restating what i've read and the options we can take with this issue

1. Do this issue as written updating docs AND adding schema validation - Sounds like this would slow us down in getting additional visualizations done if there is developer time.
2. Break this issue up to focus on the technical writing part and leave schema unvalidated - Tim or Jiaan how much developer time would we need to sync with TW to write the docs?
3. Do nothing because users won't need to setup visualizations outside the dashboards and visualization designer. Tim or Sam do we have an estimate of when editing directly in dashboards will be ready? If this happens by 16.0 I think we can go without the docs and just close this issue.

@timzallmann @jheimbuck_gl thanks for the extra details - if the schema updates are going to be large, it makes sense to hold off on doc updates that would have to be re-done right afterwards then.

so there is no primary need for actually learning and editing dashboard files.

A big benefit of human-readable files & our big differentiator compared to a GUI-only approach is that with these files we get all the benefits of MRs, versioning, etc that GitLab provides for code. For that to be relevant though, we'll need good docs that describe what the files contain. Otherwise, they'll basically be an opaque file and the git benefits are moot.

@stkerr sounds like we should move this out of the 15.11 plan then

@jiaan what do you think?

Break this issue up to focus on the technical writing part and leave schema unvalidated

it makes sense to hold off on doc updates that would have to be re-done right afterwards then.

@timzallmann @stkerr @jheimbuck_gl Thanks for everyone's input. Regarding the documentation I think it can be done in iterations and independently of the schema work at first. I think a sensible first pass could be to simply link to the ECharts documentation and add one or two examples. This would help surface the hundreds of options we support with ECharts & decimalPlaces for single stats which is currently not visible to users. This also doesn't align with our efficiency value, document everything.

I've gone ahead made this issue specific to the documentation and split out the schema work to Cube Query Rendering - Add visualization option... (#394697 - closed). Given that the documentation update I've outlined in the implementation plan won't require any engineering input besides reviewing the MR I think we could schedule this for the next milestone if there is Technical Writing capacity. What do y'all think?

Biggest question for me is that we are not that far off to have everything anyhow editable directly in dashboards and visualization designer so there is no primary need for actually learning and editing dashboard files.

@timzallmann could you link to the issue / MR that covers editing all the visualization options? I've found Visualization Options Inspector (#386833) which in the description outlines surfacing the visualization options schema in the designer as options. This seems sensible if the schema is limited to a few common options because I'm not sure how we'd support editing everything in the designer since there are so many. I could see us supporting a few common ones like axis titles & type, but supporting everything would be an immense technical & design challenge. 🤔

@timzallmann @jheimbuck_gl I think we should have at least some documentation to support users who want to get started. We can iterate on it as we add more functionality. I agree with @stkerr:

For that to be relevant though, we'll need good docs that describe what the files contain.

and @jiaan:

I think a sensible first pass could be to simply link to the ECharts documentation and add one or two examples.

I have capacity to work on this in the next milestone.

@jiaan We will support 1:1 all options of the schema also in the editor. We will do this through an universal schema driven sidebar/editor (see issue description), where we can define for each option what type it is, label, description, max/min, etc. and based on those json files the UI will be rendered. We started looking into that for the component based panels for optimize and will build it so it can be reused also in the vis designer and for all other panels.

Description File - !104077 (diffs)

Related issue too #385703

Which means the editor will support overall visualization options, options of panels, options of components in panels. And exactly that is only possible to scale through configuration then implmentation.

to have everything anyhow editable directly in dashboards and visualization designer

We will support 1:1 all options of the schema also in the editor.

@timzallmann thanks for the additional context. I'm out of the loop with any discussions regarding what's been decided with optimize or the sidebar/editor, so could you please confirm if my understanding is correct. To start off with the editors won't support all the ECharts options and the idea is to scale the support via adding to those configurations / schemas?

Exactly not supporting 1:1 e-chart options. But we will still make deliberate decisions what to expose for configurability and in the end i expect them to still be a lot.

added Technical Writing label

mentioned in merge request !112481 (merged)

marked this issue as related to #394697 (closed)

changed the description

changed title from Cube Query Rendering - Document visualization options and add them to the schema to Cube Query Rendering - Document available visualization options

mentioned in issue gitlab-org/analytics-section/product-analytics/general-discussion#18 (closed)

added workflowready for development label and removed workflowplanning breakdown label

mentioned in issue gitlab-org/quality/triage-reports#11584 (closed)

mentioned in issue gitlab-org/quality/triage-reports#11653 (closed)

mentioned in issue gitlab-org/quality/triage-reports#11715 (closed)

mentioned in issue gitlab-org/quality/triage-reports#11802 (closed)

assigned to @lciutacu

mentioned in issue gitlab-org/analytics-section/product-analytics/general-discussion#20 (closed)

mentioned in issue #405370 (closed)

mentioned in merge request !117687 (merged)

changed milestone to %16.0

added missed:15.11 label

Closing this issue as it got resolved in !117687 (merged).

closed