Pilot of this lesson content - 2022-06-15

[Sparrow0hawk]

Hi 👋

I was involved in a workshop today where I delivered some of the content from this lesson. Due to scheduling I only got through episodes 1-3 fully and started on episode 4.

I really enjoyed doing this lesson, the development of the lesson narrative from ep1 works really nicely building up concepts around what is a website. I deviated slightly from the lesson in places, after initially creating the repository in ep1 I actually jumped ahead to ep3 to set up GitHub pages. I did this just to showcase how the page rebuilds after subsequent commits to main. Next I moved into ep2 showing how to write markdown in the README.md, which worked well. In ep2 I spent some time also demonstrating internal page links using markdown prompted by a question from a participant, this led to us adding a contents section to our markdown using internal page links e.g.

## Contents
* [Learning Markdown](#learning-markdown)
* [Carpentries Lesson programs](#carpentries-lesson-programs)

## Learning Markdown
...

### Carpentries Lesson programs:
...

We updated the README.md in a number of commits and so were able to watch as the site rebuilt itself adding more each time. Next, I spent some time showing how to include images and we talked through using images from an existing URL and if the image was uploaded to the repository, cue some debate about attribution and appropriate use of images from the internet!

We moved on to introducing an index.md and explaining about separating our website files from our repository files (README.md). At this stage we were a bit pressed for time so actually highlighted the ability to select a Jekyll theme through the GitHub pages tab itself (which introduces a _config.yml file automatically) so introduced the idea of configuring the site using Jekyll and at this stage we stopped.

Overall, I found delivering the lesson excellent, my deviations were mostly just to highlight the gradual developing of the site as we commits are added but don't think this is necessary. It may perhaps be worthwhile including a note about internal page links as that is a nice feature of markdown that GitHub pages includes when building a site. I also think some of the screenshots are slightly outdated with the new GitHub settings UI so am happy to submit a PR with some new images if desired.

Happy to take any questions and thanks for making this great lesson!

[tobyhodges]

Thanks so much for this feedback, @Sparrow0hawk. I am delighted to hear that you found the lesson helpful for your workshop. If you would be willing to spend the time preparing those updated screenshots, we would really appreciate the contribution. I will keep a look out for your PRs and try to review them promptly when they come in.

I can identify a couple of other improvements we can make to the lesson based on your experience, too:

1. It would be great to add an Instructor Note to _extras/guide.md mentioning that Instructors can opt to set a theme via GitHub Pages settings if they are pressed for time, somewhere towards the end of episode 2/beginning of episode 3.
2. Add a callout with some brief discussion of image use & attribution, to reflect the discussion you had with learners at your workshop.

If you are also willing and able to take the time to make these changes, that would be fantastic. But if not, please don't worry. I will open a couple new issues about these points, so that the maintainer team knows they need to be worked on next time we get together to update the lesson. Perhaps you can comment on those issues if you want to prepare a PR to make those changes?

[Sparrow0hawk]

@tobyhodges thanks for getting back to me. I'm happy to take a look at these suggestions so please feel free to assign them to me.

[tobyhodges]

It may perhaps be worthwhile including a note about internal page links as that is a nice feature of markdown that GitHub pages includes when building a site.

My experience has been that internal page links are not always easy (e.g. they will not work "the GitHub way" in the template used for this lesson), so I am reticent about discussing them in the lesson without some sort of health warning...

[tobyhodges]

I'm happy to take a look at these suggestions so please feel free to assign them to me.

@Sparrow0hawk I have granted you write access to the repository. Once you have accepted the invitation, I will assign the issues to you, and create a third re: updating the screenshots.

[tobyhodges]

Closing this since @Sparrow0hawk's related pull requests have been merged. Thanks again for the feedback and the contributions, @Sparrow0hawk 🙌