In creating the example p5 template, Aaron ran into the following bind: He wanted the display of the visualizer to be as clean and minimalistic as possible, yet if just the entry value and progress were displayed, the person looking at the visualization would have no idea how to interact with it, which could lead to a frustrating user experience or the sense that it "doesn't do anything". Although this is a toy example, it feels like an issue that could easily come up with more sophisticated visualizers.
The "solution" in this case was to print some extra text below the progress bar with hints about the keys one could use to navigate. But that does detract from the graphic design purity of the visualization.
Hence, we have the sense that there should be reserved some space on screen for at least a micro-amount of documentation on using the visualization, or that such information should naturally and easily pop up so that the person interacting with Numberscope will effortlessly have access to this information, without detracting from the graphics of the visualization itself.
There are a lot of questions here as to exactly how best to engineer this: Is it a legend area where a visualizer that provides a bit of text or markdown or html can have that displayed? (If so, then space needs to be reserved for that.) Is it something that initially floats over a corner of the visualization but can be dismissed with a click (and if so maybe leaves a pale question-mark-in-circle information icon that can be clicked to bring it back? What is the API for visualizers to provide this? Or is it just extracted from the markdown that create's the Visualizers doc page? Is it/should it be limited just to control interactions, or should the Visualizer be able to use this micro-doc any way it likes? And how does it interact with the full doc page in the User Guide -- presumably the micro-doc automatically contains a link to that?
Note this is also related to #236 which seems more focused on the converse, that there should be active visualizations in the docs.
In creating the example p5 template, Aaron ran into the following bind: He wanted the display of the visualizer to be as clean and minimalistic as possible, yet if just the entry value and progress were displayed, the person looking at the visualization would have no idea how to interact with it, which could lead to a frustrating user experience or the sense that it "doesn't do anything". Although this is a toy example, it feels like an issue that could easily come up with more sophisticated visualizers.
The "solution" in this case was to print some extra text below the progress bar with hints about the keys one could use to navigate. But that does detract from the graphic design purity of the visualization.
Hence, we have the sense that there should be reserved some space on screen for at least a micro-amount of documentation on using the visualization, or that such information should naturally and easily pop up so that the person interacting with Numberscope will effortlessly have access to this information, without detracting from the graphics of the visualization itself.
There are a lot of questions here as to exactly how best to engineer this: Is it a legend area where a visualizer that provides a bit of text or markdown or html can have that displayed? (If so, then space needs to be reserved for that.) Is it something that initially floats over a corner of the visualization but can be dismissed with a click (and if so maybe leaves a pale question-mark-in-circle information icon that can be clicked to bring it back? What is the API for visualizers to provide this? Or is it just extracted from the markdown that create's the Visualizers doc page? Is it/should it be limited just to control interactions, or should the Visualizer be able to use this micro-doc any way it likes? And how does it interact with the full doc page in the User Guide -- presumably the micro-doc automatically contains a link to that?
Note this is also related to #236 which seems more focused on the converse, that there should be active visualizations in the docs.