Annotation and questions tool

[Tom-van-Woudenberg]

Hi @rlanzafame, @CasparJungbacker , @xjulie0x and all other interested people here,

I think it's worth discussing what is the best way for annotation and providing feedback. It think these are two different discussion, one for annotation and one for editor - user (colleague / student) interaction, with some overlap.

• Hypothesis: annotating on all pages of the book

  • positive: annotating of specific pieces of text, can work on draft-website for editor-user interaction because audience is small
  • negative: personal acount required, no admin-possibilities to remove stuff, public group is standard and distracting for everyone because note-taking for learning and feedback can happen at the same time, as there are not admin-possibilities and the annotations are not all questions it is not a correct tool for teachers to react on students
  • conclusion: useful for editor - colleague interaction

• Hypothesis as a suggested plugin, not standard for everyone: https://web.hypothes.is/start/

  • positive: annotating of specific pieces of text, annotation not visible for anyone who isn't aware of that it's public
  • negative: personal account required, for the same reasons as before + not all students interact with it it is not a correct tool for teachers to react on students.
  • conclusion: useful as a non-provided suggestion for students for annotations

• Utterances: start discussion on bottom of specific pages (example here: https://teachbooks.github.io/Sandbox/utterances/some_content/text_and_code.html)

  • positive: Linked to GitHub account (which might become a SSO-login), admin possibilities, directly leads to github issue, shows discussion at the page (no need for student to go to git environment).
  • negative: requires giving utterances-bot access to personal GitHub account, doesn't work with GitLab
  • conclusions: The only downside it that you need to give utterances bot authorization and that it doesn't work with GitLab. Those authorizations doesn't seem to involve much, but maybe one of @TeachBooks/tu-delft-cs-tas can have a look at what it really means?

• Jupyter-book issue button: directly start an issue from a page (example here https://teachbooks.tudelft.nl/engineering-systems-optimization/intro.html):

  • positive: create issues for a specific page, goes directly to the repository, works with GitLab.
  • negative: requires leaving the book to file the issue, other users cannot see the discussions directly on the same page
  • Conclusion: might be useful to investigate GitLab implementation, but I like the fluency of Utterances more. It allows for spotting issues, but not for real editor-user interaction which is visible to other (non-git) users as well

• Staticman: makes static website dynamic --> can be used for blog posts https://staticman.net/docs/getting-started, https://travisdowns.github.io/blog/2020/02/05/now-with-comments.html example: https://travisdowns.github.io/misc/comments-test.html:

  • positive: very fluent, no login required whatsover, potentially linked with issue as well?
  • negative: Requires custom set up
  • conclusion: Very useful if we can get it to work. Maybe one of @TeachBooks/tu-delft-cs-tas, can identify how feasible this is?

@rlanzafame , @CasparJungbacker , @xjulie0x , do you agree with my conclusions? Other thoughts?

[rlanzafame]

Because Utterances Issue Button requires a bit of understanding of Git I think that it would be best suited to teaching teams, but less useful with students (unless programming is part of the curriculum). Definitely agree that Utterances is better than JB the Issue Button because then you as the repo owner can control what becomes an Issue better (you don't have random people making a mess of your issue list).

Staticman seems very cool, but I can't find an example of it anywhere on the websites. Do you know of any @Tom-van-Woudenberg ?

[Tom-van-Woudenberg]

The third link shows an example page: https://travisdowns.github.io/misc/comments-test.html

[Tom-van-Woudenberg]

I agree that having a GitHub account (SSO login or not) is a confusing step for students if there's no programming

[rlanzafame]

Sorry, my comment was confusing, I edited it a bit. I meant that Utterances is better than Issue Button because the Issue Button sort of only makes sense if you know about GitLab/GitHub and Issues. It's the same for GL and GH. And GH beats GL here anyway because TUD externals can't simply make a GL account to comment on a book

[rlanzafame]

but also, thanks, I missed that example before. I am less positive about staticman now after seeing it, though. Having to process a lot of PR's seems like it might be a deal breaker (at least for me) because a) you can't guarantee real time comments, b) you have to do something to add the comment, 3) the PR may be difficult to merge if you have a lot of edits in the pipeline that overlap with the commented page. So if it's an edit/correction from a student, you might as well just make the change instead of merge a PR. If it's a discussion about the sope/content i think i like Hypothesis better.

[Tom-van-Woudenberg]

Ah, I missed the part of the PR in that process. That's not good. Probably you can set it up to do it automatically, but requiring a rebuild of the website is far from ideal (not fluent, 'where is my comment?)

[rlanzafame]

I start a new comment here to see if we can approach it another way: what would be the ideal features we want in a collaboration tool?

• no login, but only if you don't mind getting spam or nasty comments and can easily moderate it
• login if you need to know who comments and don't mind identities being public
• login in a trusted system so that there's a way to track you're own comments and identifications should be required anyhow
• moderation system should be easy (more like hypothesis, but not a PR like staticman?)
• ability to make your own private comments (this is like the "personal book" idea)
• system makes it easy to go from a comment/suggestion to an edit (e.g., opens file in webide)
• Standard behaviour: Not be distracted by the system when you don't want to use it
• ...

[rlanzafame]

yeah, it stays there on the page, but didn't show up in the public list.

[Tom-van-Woudenberg]

Which list? I also see it on the website itself?

[rlanzafame]

ah the one in the link here, it's a list of all your posts as a user. only one public post is visible on that page

[Tom-van-Woudenberg]

But that's what I clicked here right: https://github.com/orgs/TeachBooks/discussions/7#discussioncomment-9130505 ?

[rlanzafame]

oh yeah. ignore me

[rlanzafame]

I also created Discussion 8 (personal version of book), which may have some overlap here.