04/03/24 User Test Updates

[garrettmflynn]

1. Add a sentence to describe that the tutorial and the GUIDE should be open alongside each other
2. Indicate Settings is at the bottom of the sidebar
3. Note that ~ means home in each case
4. Remove Start page
5. Indicate .ap.bin to reduce confusion
6. Tell users to press Next more often
7. Indicate the user should take more time on the Metadata page to fill out personal info
8. Remove "complete as normal" and, instead, enumerate repeated steps
9. Add preform option to specify a global base_directory for the Locate Data page
10. Fill out Phy before SpikeGLX on Locate Data section of the tutorial (as it is listed first in view)

[CodyCBakerPhD]

What would you think about styling the one-line action items for a user with a specific icon to draw attention to?

[garrettmflynn]

What would you think about styling the one-line action items for a user with a specific icon to draw attention to?

Are you specifically thinking the list in the Dataset Publication "Workflow Setup" section, or also other places in the tutorials?

Since we're providing commands throughout, I'm finding it somewhat difficult to scope when and where to use such icons.

If it's a list, we really don't need more than one icon to denote a specific type of section. But as it stands, highlighting the "Workflow Configuration" header with a special icon here would be confusing because we configure a workflow in most of the tutorials.

[CodyCBakerPhD]

Are you specifically thinking the list in the Dataset Publication "Workflow Setup" section, or also other places in the tutorials?

Everywhere

[CodyCBakerPhD]

All text in the tutorials is either an action the user should take, a comment about context of the page (associated with snapshot), or a note about additional details - we already have the special styling for notes, so it's more to highlight what that first user test asked for in the way of knowing what to do and when to do it

Example:

The tutorial we’re working with uses the SpikeGLX and Phy formats, a common output for Neuropixels recordings and subsequent spike sorting. To specify that your pipeline will handle these files, you’ll press the “Add Format” button.

of https://nwb-guide.readthedocs.io/en/latest/tutorials/single_session.html#data-formats

Could be

The tutorial we’re working with uses the SpikeGLX and Phy formats, a common output for Neuropixels recordings and subsequent spike sorting.

📢To specify that the pipeline will handle these files, press the “Add Format” button.

[garrettmflynn]

While I think this could help with skimming, I'm hesitant to add icons since the whole purpose of a tutorial is to provide all of these bits of information. Additionally, simply adding an icon before the text isn't super pretty; it'd be ideal to have notes with different formatting (e.g. Docusaurus admonitions) or a list-like structure but with an icon instead of bullets.

A less intrusive option would simply be to ensure that actions are separated onto a new line—as you've done above, but removing the icon.

The closest I've seen to this in the Divio docs is this page that outlines some user selections as lists instead of inline: https://docs.divio.com/introduction/django/django-02-create-project/#gsc.tab=0

Do you have any other examples of this in other tutorials?

[CodyCBakerPhD]

Not off the top of my head, but all the tutorials I know of are for people who are knowledgeable about the programmatic side of what the content involves - I'm just thinking about ways to visually clarify our latest user testers concern about not knowing what to DO (as an action) and when to do it in between all those lines of text - for example, if the eyes scan too fast and skip a particular line

I agree that the docusaurus approaches visually appear the best for pure text deviations, but they are all fairly 'extra' (tips/notes/info) or negative (warnings/errors), I was just thinking somewhat neutral

I'll keep my eyes peeled for examples with this

[garrettmflynn]

Sounds good. Do we want to implement an intermediate solution or open a separate Issue / PR so we can get this one through?

[CodyCBakerPhD]

Sounds good. Do we want to implement an intermediate solution or open a separate Issue / PR so we can get this one through?

raised #734

[garrettmflynn]

Gotcha thanks!