Help site for Classroom

[ddbeck]

Feature request :sparkles:

(notifying @srinjoym, since we've discussed this before 👋 )

Description

I propose having a central help site for Classroom. This site would put, in one place, content (or links to content) that helps teachers complete tasks with Classroom, use best practices, or seek out additional help. This would include:

• existing Markdown in /docs and the README file
• the existing video help page
• links to the GitHub blog, GitHub Education Community, and repo issues
• new content, written in Markdown

Proof of concept

I've set up ddbeck/classroom-docs-prototype to demonstrate what the help landing page and related content might look like.

Some highlights:

• You can see a new documentation page and its corresponding source.
• The site is generated with Jekyll and GitHub Pages with the Primer theme. It doesn't require any new code or build process (though it might be desirable to introduce linting, spell check, etc. later). It could be merged into this repo (in the /docs/ folder) or stand alone.
• It uses the Primer theme and demonstrates extending it with a warning CSS class in style.scss. This lets us use a conventional GitHub Primer style without forking to get Classroom docs-specific customizations.

Some open questions:

• I'm not sure how we'd best integrate this content into Classroom. It's a little bit untidy to have the help content on another domain, if hosted through GitHub Pages. It would also be inconvenient for anyone self-hosting Classroom (if that's something anyone is doing, I wasn't sure).
• GitHub Pages doesn't have an approved localization plugin. To allow translations of original content, we'd have to do some awkward tricks with Jekyll or look at building the site without GitHub Pages. At that point, we could consider other Markdown-based site generators as well, which might have preferable localization stories (e.g., Hugo's multilingual mode).

I'd love to get your feedback on this idea. Thank you! 🙇

[srinjoym]

Hi @ddbeck 👋

Fantastic work on this! ✨ The prototype website looks great, and the content will be really useful for teachers and students. For an initial go at integrating this into Classroom, I've created a Draft PR here: #1794

I think the best course of action here is to integrate this into Classroom directly. We don't have to add that much overhead in terms of technical complexity and it'll likely be easier to maintain and add docs in the future if everything's on the same repo.

In the draft PR, I've added in Markdown rendering support using the [Redcarpet (https://github.com/vmg/redcarpet) gem. The idea is to be able to automatically render any of the markdown files in the docs folder in the Classroom repo on the /help route on Classroom. This way we can easily add new pages in the future by just adding a new markdown file in the docs folder.

Let me know what you think of this approach! There are definitely still some open questions with regards to things like localization, but hopefully this is a good start. If this sounds good, feel free to start working on some of the issues I've outlined on the draft PR!

[ddbeck]

Thanks for your patience while I got a chance to look this over, @srinjoym. All of this looks really promising. I think the draft PR looks like a good start and the task list makes sense to me. I'll start working on it by the end of the week! Thank you again!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. Thank you for your contributions.

[EricPickup]

Finished in #1794 🚀