blog example

[rlanzafame]

Hey @katiagatt and @mardiamanta here is a rough outline of a "blog post" we might have on the website to give you an idea (text is not final, and would include a few sentences at the top describing that we did a teachbooks workshop/demo at a Dutch physics conference).

Observations

Collected by Robert, Tom and Julie after the session.

1. No one followed the instructions (neither the 10 clicks nor the actual workshop exercises)
2. Participants often asked a question or were stuck, then later discovered that the problem was not reading the instructions
3. The pptx as used is a good basis.
4. 1 hour is definitely too short to get through everything.
5. It is difficult to switch back and forth between several tabs
6. After using template, the step to start with the exercises was not clear
7. Directories in the book wasn't clear
8. First Actions run broke for nearly all participants
9. Creation of GitHub account caused confusion
10. Decision about private/public repo caused confusion
11. Some participants were overwhelmed by the complexity (scope of workshop not clear to them in advance)
12. Not clear for whom a TeachBook is best-suited (related to above point)
13. Clearly two groups: one familiar with the tools (git, github, python), others not. No one seemed to be an "expert," but some seemed to have experience using notebooks with experimental data collection (I/O data streams).

Ideas for improving the workshop (activities)

Consider more like 2 hours, including the pitch/introduction.

Things to definitely do during the pitch/introduction:

• Explicitly point out the GitHub account creation considerations
• Explicitly point out the importance of creating public repositories for the workshop and encourage this to be their "default" behavior in the future
• Have participants self-identify their personal skill/experience level. Create pairs/small groups based on this and class size
• A demonstration of the 10 clicks (and have participants do it at the same time) as many early questions came from participants not reading/following the instructions (e.g., Actions setting not changed).
• Explicitly state how participants are expected to work in the remainder of the workshop (e.g., number of tabs to use, etc.)

A paired setup with 2 screens could be very beneficial, as it would allow one screen to show instructions, the other for carrying out the steps. Use the self-identified skill/experience of participants to create pairs.

When creating a repo clarify that public is better, but also indicate what can change (or not) at a later moment. Would be worthwhile to emphasize the importance of keeping things open and CC BY in general.

Ideas for improving the content

Overall the instructions should be made more motivating. Right now they are factually correct but just a long list of text. Boring!

These were common issues that should be included as exercises in the template book:

• bad toc (typical stuff with file paths; someone also accidentally added a _ as the first character in the first line - this would be a good "challenge" exercise)
• adding a content file in repo_root/ instead of repo_root/book/
• not being able to find the Actions tab (or read/navigate the contents)
• using the correct repo: not being able to find the one they created, perhaps looking in teachbooks org repos (some did PR to template, not a partner repo)
• not setting up actions fast enough, causing first build to fail. how to restart/redo the first build (re-run job or make an empty commit)

A concise checklist for creating a GitHub account quickly (manual page)

• tips for which email to use (note that more can be added later)
• reminder that the username/handle is important as you may use it in work and personal situations
• include screenshots/descriptions of some of the things that don't matter (GitHub survey questions)
• maybe a 2FA note is needed?

[Tom-van-Woudenberg]

Ideas for improving the content has been converted to issues: TeachBooks/manual#57 and TeachBooks/template#42

[Tom-van-Woudenberg]

@rlanzafame , I've added the workshop-discussion here: https://github.com/TeachBooks/workshop/discussions/1