instructor-notes compulsory?

[drmowinckels]

I really love the workbench, its an excellent piece of work, and looks so much nicer and more contemporary. I find it generally easier to generate, serve locally and work with.

As i'm working on creating a new incubator lesson, I have some questions as I'm creating them, that I cant seem to find the answers to in the docs. Sorry if the questions belong to the docs repo in stead. Transfer if need be.

1. is the instructors/instructor-notes.md file mandatory? I'm getting build errors if I remove it (or name it something else), but can also not see where its rendered in the final site.

Error in normalizePath(path, winslash = "/", mustWork = TRUE) : 
  path[1]="/Users/athanasm/workspace/conferences_workshops/swc/r-tidyverse-4-datasets/instructors/instructor-notes.md": No such file or directory

2. My lesson has some general instructions on how to "read" code, that I'd love to create a glossary for for the instructors. But creating an instructors/glossary.md file wont appear in the served site. not as I can see.

So, a follow-up to these two first questions:

3. Are files in the instructor/ folder supposed to follow the same naming convention as in episodes to show up in the instructors view of the site? And is there a system for creating other instructors notes not necessarily tied directly to episodes, but rather to general content?

   • I just saw that instructors notes can be added as asides carpentries/sandpaper#26 , which is lovely! I just want to understand how that and the instructors folders work/complement each other

4. where is the glossary rendered? I've added a glossary.md to instructors/ and learners/ folders, but cant seem to understand where these should be rendered on the site.

EDIT

• ok, I just realised where the learner glossary and instructor-notes.md are rendered, but I found it a little hidden.
• is there a way to make the top nav more visible? I just actually didn't notice it was there.
• and perhaps add a single line beneath the nav section you are at, to make it clear where on the page you are?
• the expanding aside where the episode list is, is great, but also somewhat hidden in what it actually contains when not expanded. Perhaps renaming "Expand" to "Episodes" ?

[drmowinckels]

I now know also why I have not noticed the upper nav. I'm viewing the local rendered page in RStudio Viewer pane, where the top nav is not displaying for me when its a certain width (being narrow), so I have actually been working on the lesson without knowing that nav was even there.

It might be good to have a good look though mobile view of this and make sure that the nav still renders in some way even with a narrower browser window

[zkamvar]

Hi @Athanasiamo, I've seen this and I will respond soon :)

[zkamvar]

is the instructors/instructor-notes.md file mandatory?

At the moment, consider it mandatory, but thinking about it: it does not need to be mandatory. I can create the file if it does not exist.

[zkamvar]

My lesson has some general instructions on how to "read" code, that I'd love to create a glossary for for the instructors. But creating an instructors/glossary.md file wont appear in the served site. not as I can see.

Short answer: The glossary will be in learners/reference.md under the heading ## Glossary

Long answer: This is one of the things I need to add to the template 🤦🏼. Right now, the established pattern for the glossary is in a file called learners/reference.md under the heading ## Glossary (example from the lesson development training). This is a pattern established from the previous infrastructure and thinking about it now, it's kind of cumbersome. In the future we want to be able to use glosario to auto-build the glossary from entries within the lesson. I'm not sure where to go with this at the moment, but I will be exploring solutions in the future.

[zkamvar]

3. Are files in the instructor/ folder supposed to follow the same naming convention as in episodes to show up in the instructors view of the site? And is there a system for creating other instructors notes not necessarily tied directly to episodes, but rather to general content?

There are a couple of things going on here:

1. The underlying philosophy of the workbench is that the central content are the episodes themselves. Anything outside of the episodes addresses things that require extra cognitive load or are outside of the scope of the lesson itself.

2. The episodes don't have to have any special names. The reason they are numbered by default is largely historical. As long as you list episodes in the config.yaml file, they can have any names you want.

To answer your question about instructor notes: Creating general instructor notes that are more general and not tied within episodes is to add them to the instructors/instructor-notes.md file. When the lesson is built, the episode-specific instructor notes are appended to the page.

[zkamvar]

ok, I just realised where the learner glossary and instructor-notes.md are rendered, but I found it a little hidden.

I agree that I haven't done a good job at making this more obvious. I'll try to improve the documentation.

is there a way to make the top nav more visible? I just actually didn't notice it was there. and perhaps add a single line beneath the nav section you are at, to make it clear where on the page you are?

I think adding a border will make it more visible. At the moment, the hamburger menu doesn't necessarily look like it can be clicked on, but a border will certainly highlight that. I've opened https://github.com/carpentries/varnish/issues/48 for this.

the expanding aside where the episode list is, is great, but also somewhat hidden in what it actually contains when not expanded. Perhaps renaming "Expand" to "Episodes"?

I think this makes sense. I've opened an issue in varnish: https://github.com/carpentries/varnish/issues/47

[zkamvar]

Additionally, because this issue goes beyond the scope of sandpaper itself, I'm going to transfer this to the workbench

[zkamvar]

It might be good to have a good look though mobile view of this and make sure that the nav still renders in some way even with a narrower browser window

I believe the reason why the nav doesn't take up space on narrow browser windows is a concern for accessibility (you can see the process we used to design the frontend here: https://carpentries.org/blog/2021/05/lesson-template-design-process/) and the hamburger menu in the top right is the solution, which will be more obvious once we address carpentries/varnish#48

[zkamvar]

And once again, I realise that I have been a terrible host. Thank you for your detailed feedback @Athanasiamo! I really appreciate you taking the time to highlight these areas for improvement

[drmowinckels]

you've been a great host, no worries @zkamvar . Your answers are thorough and thoghtful, its all good :)

I did realise something else about the nav too. So, when in wide browser, everything looks fine. When narrowed, the nav dissapears and a "hamburger" appears. Now, this is all as expected, imo. The unexpected is that the content ov the hamburger nav when expanded, is not the nav links as in the nav for the wide view.

So, the hambuger expands into episode list, but the nav links that exist in the wide browser are no where to be found (at least I cant find them). It looks like we'll need to have a thorough look into the nav creation. Having experience with creating Hugo Themes, I always find navs tricky, so I can see how this can be missed.

[zkamvar]

Indeed, navbars are tricky AF, and I've opened https://github.com/carpentries/sandpaper/issues/306 to help me track this thank you!

[drmowinckels]

for my part, all my questions have been answered or moved into meaningful new issues. SO we can close this is you dont have a need for it.

[zkamvar]

Thank you for your feedback and attention to detail!