How to store instructors' notes inline

[gvwilson]

Should we store instructors' notes in the lesson episodes themselves, rather than in a separate file? If so, how should they be presented? As an icon which produces a pop-up when clicked? As an accordion section (expand/contract) in the main body of the lesson? Or...?

[mstimberg]

I guess another alternative would be to have a completely separate "instructor version" of each episode which uses a different style sheet to, say, displays the instructor notes in a separate column on the right.
I personally am a bit sceptical about an interactive pop-up/expand mechanism for this purpose: assuming that the notes are written with instructors, not learners, in mind, having buttons to display this information might be distracting for learners using the material. Conversely, they would be less discoverable than they probably should be for the instructors (e.g. it would be easy to overlook a little [+] that when expanded says "WARNING: make sure that ... before continuing").
Maybe an intermediate solution would be a button on the page switching the whole page to "instructor mode", showing all the annotations?

[abostroem]

I would like a button that allows me to view the lesson with or without instructor notes rather than having to continually click to expand every note.

We should also think about how to print the two versions.

[tomwright01]

For embedding comments I'm +1 for a multi-modal page i.e. instructor / learner views.
For challenge solutions, a show / hide approach (on a per-challenge) basis would be better here.

[tracykteal]

I think there's too much content in instructor notes to simply embed them in the lessons. I'd be -1 on doing away with instructor notes pages.

Something like hypothes.is could be a complement though. Or be a way to ask questions about components of the lesson or have conversations about sections.

I think hypothes.is would be one of the best solutions here, although there would be a few logistics to sort out. We could even set up groups, so just instructors can view the comments, and it's not adding content or confusion to learners' view of the lessons. @ctb did this for a Data Carpentry workshop, and it worked well.

cc @judell

[mstimberg]

I think there's too much content in instructor notes to simply embed them in the lessons. I'd be -1 on doing away with instructor notes pages.

I think there might be room for both: general notes in a separate document and specific notes inline. E.g. using the git lesson as an example (http://swcarpentry.github.io/git-novice/instructors.html), we could keep a remark like "Drawings are particularly useful in this lesson: if you have a whiteboard, use it!" in some general instructor notes but move a specific remark like "When you do git status, Mac users may see a .DS_Store file showing as untracked. This a file that Mac OS creates in each directory." to the point where git status is introduced.

I think the main problem of the separate file is that it quickly becomes inconsistent with the lesson content. E.g. for the shell lesson (http://swcarpentry.github.io/shell-novice/instructors.html), the instructors notes still talk about data while the directory has been renamed to data-shell in the lesson (well I should probably simply open a PR about this one ;-) ).

[gvwilson]

Thanks for your comments - here's a combined proposal for voting:

1. Some instructors' notes embedded in the lesson with a single button that shows or hides all of them (i.e., toggles between student view and instructor view).
2. Keep the separate _extras/guide.md page for lengthier or more general notes.
3. Support external comments via https://hypothes.is/.

Please vote using the smiley-face button as usual:

[fmichonneau]

How does hypothesi.is deal with annotations when the lesson gets updated?

For instance, if someone annotates a paragraph to point out a problem, and the problem gets fixed in the lesson, does hypothesi.is recognize the content has changed and removes the comment, or does it leave it until someone manually removes it? Does this someone have to be the person who wrote the comment?

I really like the approach of hypothesi.is, I'm just concerned that it'll be yet another place we need to check to keep everything in sync.

[ctb]

Hi Francois,

they have fuzzy matching implemented in such a way that, if no match can
be found, the annotation is removed.

Annotations that still match can only be removed by the author, however.

best,

--titus

C. Titus Brown, ctbrown@ucdavis.edu

[tomwright01]

@fmichonneau I also had this thought. I may be wrong but I don't think there is a way to deal with this. There is also no way to not support hypothes.is, any user can post comments to any page. In my view enabling the page just demonstrates that we are open to feedback from the user community.

Another thought: An potential way to use this tool would be to create a group containing participants at a workshop, h could then be a substitute for etherpad conversations.

[judell]

I'm just concerned that it'll be yet another place we need to check to keep everything in sync.

Indeed. I'm prototyping a notifier at the moment, currently it goes to Slack, but I'm curious to know what other modes (beyond email) would be useful in your world.

potential way to use this tool would be to create a group containing participants at a workshop

Yes. Note that the annotations are then only visible to group members. If that's what's wanted, then great. If not, there are API-based ways to show them more widely.

[k8hertweck]

I'm also concerned about complications from over-engineering related to multiple methods of providing instructor notes. I know some instructors are already overwhelmed with having to look multiple places for resources related to running workshops. Regardless, I'm happy to try this approach and reassess down the road.

[mikej888]

If it is possible for students to print handouts with the visible solutions but without the instructors' notes that would be good.
I can see the value of supporting external comments via https://hypothes.is/ on a workshop-specific basis, to allow attendees and instructors to record their concerns/suggestions (which could then be munged into changes to the lesson).

[iglpdc]

I don't see the need for embedding the instructor notes in the lesson and think it's an over complication. In my opinion, the html version of lesson should be only used by the learners, either when learning by themselves or reviewing the lesson after a workshop. Notes in the lesson (say with hypothes.is) should also address learners.

On the other hand, instructors should only use the instructor lesson when preparing to teach. For obvious reasons, we have been exclusively developing the lessons until now, putting very little of the instructor's experience back in the guide, but I think this has to change now we have pretty stable core lessons.

I prefer this separation because there are parts belonging only to one of them. For example, when using the instructor's guide, I probably don't need the ouput of all the commands, and learners don't need to see all the explanations on how to teach a particular piece.

So my preferences go for a separated instructor guide, probably in several files, easy to print and view in browser, that suffices for a new instructor to teach the lesson without further help.

[gvwilson]

Consensus seems to be to leave instructors' notes in _extras/guide.md.