From zero to teaching: Facilitating a smooth developer journey for new teachers.

[SilasBerger]

The intent of this discussion is to take on the perspective of a third-party teacher who wants to deploy their own instance of the teaching platform (frontend + API). The purpose of this reflection is to gain a better understanding of the architectural requirements involved in making their developer / user journey as smooth and seamless as possible.

Definition: A user in this context is any person who deploys or wants to deploy their own clone or fork of teaching-dev and teaching-api.

The journey of a new user

As a new user, I want to:

1. Clone teaching-api and fork teaching-dev.
2. Configure my environment variables for teaching-api and deploy it as-is.
3. In the frontend, customize the site title, navbar items, footer items and home page / landing page.
4. Add my own Markdown docs and pages.
5. Implement custom components with and without persistance (potentially with custom stores), to use in my Markdown docs / pages.
6. Potentially implement custom Remark / Rehype plugins.
7. Define which class gets to see which docs by specifying it in a config file (yaml).
8. Set up the required accounts (Microsoft, Algolia, etc.).
9. Configure my environment variables for the frontend, deploy it, and have it fully operational (including login, full-text search, etc.).
10. Set up a weekly job that pulls the teaching-dev-main into my fork and creates a PR, without any conflicts or changes to my customizations.

What we need to consider

• Document the process to go from zero to a fully deployed and potentially customized frontend and API.
• Key: Define interfaces between stock and custom code in a way that allows for customization without leading to conflicts or unwanted changes when pulling the latest teaching-dev. Some interface points that come to mind include:
  • docusaurus.config.ts: Navbar items, footer items, plugins.
  • Landing page.
  • rootStore.ts: Custom stores for custom components.
  • Files related to the documents API: Custom document types.
• Authentication: Users may want to work with local accounts or provide their own IDP (e.g. Keycloak), rather than using the Microsoft Cloud.

[SilasBerger]

One important question is how users upgrade (or downgrade) the teaching-dev version in their app. Here are some strategies:

• Work on a teaching-dev fork and merge upstream changes into your own repo. Advantage: Git support. Disadvantage: Downgrading is difficult, plus potentially unwanted changes (e.g. img/favicon.ico, img/logo.svg).
• Offer a CLI similar to this idea that copies files from a local teaching-dev clone into the user's own application. This means you can also set teaching-dev to a different / older version, run the sync task again and have the changes reflected in your own repo. The disadvantage is that it's a bit messy, and we also have to be careful with what files should and shouldn't be synced.
• Turn teaching-dev into an npm package and expect users to provide some main.ts entry point with a call like teachingDev(siteConfig). That way, they simply specify their targeted teaching-dev versions in their package.json like with any other dependency. The challenge here is that we are wrapping a framework. We'd have to see to what extent Docusaurus is willing to accept a file structure that differs from the convention (e.g. docs being located at ../../docs relative to node_modules/teaching-dev/docusaurus.config.ts).

[lebalz]

As discussed, i like this idea!

We could think about providing a simple create-teaching-website package that bootstraps the project. As a reference, docusaurus does it like that: create-docusaurus.

For our usecase, we could then run

npx create-teaching-website@latest xyz-teaching-inf