Collection of comments on the Workbench

[anenadic]

This is an issue to collect some feedback on the use of Workbench:

1. open external links in a separate tab by default
2. actually, is there a way to control how individual links are opened in general (in the same tab or a separate one)?
3. Search button only seems to search within the page and not within the site
4. This is not a criticism of the Workbench itself as this is how the old lesson template was designed as well - but I wonder if we should be mixing in workshop operations things into the lesson content - for example we have "episodes" for breaks and when reading the lesson, this adds an extra click for the person. I think these breaks are part of a suggested workshop schedule on how the course can be delivered but should be separated out from the lesson content. Even more so as people may not make breaks at the same time as suggested - I often have this with instructor training which suggests one 15 min break per half fay of teaching as we normally break two times. The old lesson template also implies that IT will be delivered over 2 days as we have seen during pandemic that is not always the case. The new Workbench does not have this issue but I'd still consider separating the schedule of delivery out of the content (i.e. the breaks).
5. navigation menu on the left does not stay 'collapsed' between page refreshes or navigating between pages - it should stay 'collapsed' or 'expanded' until that is changed
6. too big top padding on headings - as this is a matter of personal preference, can this be controlled by a lesson designer?
7. Section headings - feels like there is little difference between heading3/4 etc. - need to review this myself to be sure - again a matter of personal preference but still putting it here
8. Add examples of all types of fenced divs in the Workbench documentation

[anenadic]

Comments on the Workbench from Shoaib Sufi, community lead at the Software Sustainability Institute:

" Really liking the new template! Makes it even easier to promote the Carpentries way!
Looking around more - it’s actually beautiful - in the same way Read the Docs format is - actually I might prefer the Carpentries one - is it custom or built off of an existing template? "

"Loving the responsive design also - well done to the team who put this together! Back to the content - some really fantastic stuff here. "

[zkamvar]

Thank you for collecting this feedback, @anenadic! I've transferred this issue to the workbench repository so that it's clear that this is feedback about the workbench in general as opposed to the documentation, specifically.

open external links in a separate tab by default
actually, is there a way to control how individual links are opened in general (in the same tab or a separate one)?

In general, you can open a link in a separate tab/window by using ctrl on Windows/Linux or cmd on Mac and clicking the link.

There is a good reason why we do not have links open in new tabs/windows by default: it takes away user autonomy. While it's possible for users to hold a special key (e.g. ctrl on Windows/Linux or cmd on Mac) and click on the link to open it in a new tab/window if the link uses the default setting, if a link always opens in a new tab, it's not possible to have the behaviour open in the same tab/window. More reasons can be found in https://css-tricks.com/use-target_blank/

Search button only seems to search within the page and not within the site

See #8

This is not a criticism of the Workbench itself as this is how the old lesson template was designed as well - but I wonder if we should be mixing in workshop operations things into the lesson content - for example we have "episodes" for breaks and when reading the lesson, this adds an extra click for the person. I think these breaks are part of a suggested workshop schedule on how the course can be delivered but should be separated out from the lesson content. Even more so as people may not make breaks at the same time as suggested - I often have this with instructor training which suggests one 15 min break per half fay of teaching as we normally break two times. The old lesson template also implies that IT will be delivered over 2 days as we have seen during pandemic that is not always the case. The new Workbench does not have this issue but I'd still consider separating the schedule of delivery out of the content (i.e. the breaks).

I agree with this. This is one reason why we de-emphasized the presence of the schedule on the landing page (e.g. you need to visit the instructor landing page in order to view it). Ultimately, though, this is an issue for individual lessons and maintainers.

navigation menu on the left does not stay 'collapsed' between page refreshes or navigating between pages - it should stay 'collapsed' or 'expanded' until that is changed

This is a good point. I believe I might be able to use browser cache to handle this, but it will require some investigation. I will open an issue in {varnish} and address it once we are nearing the end of the beta phase.

too big top padding on headings - as this is a matter of personal preference, can this be controlled by a lesson designer?

I believe this was implemented with accessibility in mind, but will be exploring ways to allow custom CSS to be added (though official lessons should not deviate from the styling).

Section headings - feels like there is little difference between heading3/4 etc. - need to review this myself to be sure - again a matter of personal preference but still putting it here

Thank you for this feedback! I'll have to go back to the Figma files and make sure our CSS matches the spec.

Add examples of all types of fenced divs in the Workbench documentation

We have a component guide linked in the callout blocks section of the documentation

[anenadic]

A suggestion: wonder is capitalising/titlecasing headings should be done automatically and via a configuration parameter?

[zkamvar]

This was a design choice from the contractor who designed the frontend. In the limited examples, it worked well, but I think I am going to disable this "feature" since there are many circumstances in which having control over casing (e.g. including function names in the title).

[longr]

I'm going to add a comment here, as I am not sure where is appropriate, but the Overview box at the start of a lesson is very compressed. If the side bar is not collapsed, the text is very compacted so that "Questions" is limited to 2 / 3 words per line harming readability.

[zkamvar]

This is a good point and with the little real estate afforded when the sidebar is expanded, there's not much that we can do at the moment 😞. Hopefully this is mitigated with varnish 0.2.0 where the sidebar behaviour is persistent between episodes so that the objectives are not always squished.

[longr]

That will help, but when learners want the sidebar out or are using split-window / 2 windows (webpage and terminal for instance), it will be squished again. I am guessing there was some design reason to go side-by-side instead of the on top. Perhaps it needs revisiting.

[zkamvar]

It does need revisiting and I will revisit it when I get the chance. For future reference: because the questions/objectives are special to lessons, they are treated with lua filters in {sandpaper} in combination with CSS styling in {varnish}.

[anenadic]

Looks like point 8. on including examples of fenced divs is at: https://carpentries.github.io/sandpaper-docs/component-guide.html#top under 'More' menu - this could perhaps be made more prominent under '1. Introduction to The Carpentries Workbench' section. Just noting it here - we could link to the transition guide here too: https://carpentries.github.io/workbench/transition-guide.html (this is possibly already done).

[zkamvar]

Hi @anenadic, I think these are good suggestions! Do you want to make an edit to the first episode with the link to the component guide?

The transition guide does not explicitly link this page, but I will add it in https://carpentries.github.io/workbench/transition-guide.html#callout-blocks