Some docs for visualizers, especially controls, should be concurrently visible in app (not just docsite).

[gwhitney]

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.

[gwhitney]

This seems closely tied to the "link to visualizer documentation" item that was today scheduled for alpha; we can likely just fold that into this issue. So giving this an alpha milestone. See https://github.com/orgs/numberscope/discussions/6#discussioncomment-9980977

[gwhitney]

Resolved at Oct 29 meeting: for alpha (i.e. this issue) just have easilyt visible hyperlinks to doc pages for visualizer and sequence in their respective tab. Add beta issue to have a on-screen info box that shows controls/key commands)

[gwhitney]

I am looking for a way to put in these links without making the 'scope screen too busy. There is already a change button to the right of the Visualizer and Sequence names. Also, there is a "? in circle" info icon in the entry box for the name, but it just pops up a tooltip; it's not a link. So although I would be OK with putting that same icon within what looks like the entry box for the sequence name, I am reluctant for it to have different semantics, and I am reluctant to use a different icon for the sake of making the screen overwhelming.

So:

Proposal 1: I have made the links in the docsite go to the Numberscope accent color (that sort of pale bluish with maybe a hint of lavender) on mouseover to make it just a bit clearer they are active. Extend that same convention to the 'scope for all elements that work like links. Make that ?-circle into a link also, going to the appropriate section of the user guide about saving and loading specimens (which section does not yet exist, but will soon). Then use that ?-circle icon (without any tooltip, unless someone has a proposal for one) within the "pseudo-entry box" for the sequence and visualizer, positioned in the same way as in the name change box, to link to the pages for the current Visualizer and sequence.

or:

Proposal 2: Assume that the "pseudo-entry boxes" for the sequence and visualizer make it sufficiently tempting to click in there to change them. Ditch the change buttons to the right of these boxes. Put a new different documentation/information icon (like maybe the international i-in-circle information icon 🛈 that is a Unicode character) in a similar position within the "pseudo-entry boxes" as the ?-in-circle is in the specimen name box, and make them links to the proper doc pages.

or something else/some other combination of the ideas in Proposals 1 and 2? Need more guidance to proceed here.

[gwhitney]

(I really just wanted to set a new record of six tags on this issue ;-)

[gwhitney]

Proposal 3: put either the ?-circle icon, if we make it a link, or a new info icon if we don't, just at the end of the brief description string that is already there under the name. It will be smaller/less prominent there but still quite noticeable if you're looking for it. And it should not increase the busy-ness too much there.

[gwhitney]

Proposal 4: the whole description under the name box just be a hyperlink.

I will implement this just to get something working, as it is the simplest to do and will easily be changed. But this alone is not a final solution because right now there is no visual indication of links on the frontscope page. So although the description will then work as a link, there will be no indication to the visitor that the description can be clicked on for more info.

[gwhitney]

In terms of the eventual desire to show controls as well, if we land on a consistent icon that pops up info that can also be clicked on for more info, the popular in the case of a visualizer can just be the controls section of the doc page. If we decide to go that way, I can just implement it all at once for alpha. (That part was deferred to beta primarily because we had no design.)

[gwhitney]

Proposal 5: make the Documentation item in the top bar a drop-down that always has just

• link to doc page of current visualizer
• link to doc page of current sequence
• link to documentation home. If we did this, we could fold about into this drop down as well, so there would be just two items in the top right.

Proposal 6: add an item in the right hand end of top bar for the documentation of the current visualizer, next to the existing Documentation link. l think adding two items (for the sequence, too) would be too many. But we could replace documentation with the combo of visualizer and sequence doc pages, and make the numberscope logo go to the documentation home page

[gwhitney]

I tried Proposal 4, see https://github.com/numberscope/frontscope/pull/486#issuecomment-2466498459. I definitely don't think it is the way to go; the intention of the whole description being a link seems very murky to me. So hopefully sometime soon we can converge on one of the other proposals, or something else that someone brainstorms.

[katestange]

I consulted with my older son (I think the younger generation is a good resource) and he independently suggested the documentation link pop down a menu. He said we could even put all the documentation as a pop-down under Numberscope, and pointed out that popdown menus are nicer on the left of the page generally. I gave all of these options some thought, trying to imagine the navigation in my mind's eye, and I think a pop-down menu of some type is the most discoverable option as well as the least cluttery.

[katestange]

I don't think hiding everything under the Numberscope logo is discoverable, though. But the left-right thing is an issue. On the right, a pop-down will cover the default panel area.

[gwhitney]

OK, as a prototype to look at for our discussion, in #486 I will implement the following:

1) Make the Numberscope logo go to the about page 2) Ditch "About" at the top right 3) Rename "Documentation" to "Help", and make it a drop-down, with sub-items " Visualizer", " Sequence", and "Documentation", where the blanks are filled in by whatever is currently in use.

I am not too worried about the "Help" dropdown obscuring the parameters, since it will only be dropped down when you mouse over it or click it, and if you click it, presumably clicking it again makes it go away.