Repository navigation
CreateOnboarding documentation #761
Description
On our MathCAT meeting on September 9, we discussed the development of an "MathCAT Onboarding" document. George and @rileeki
agreeded to get started on this work.
We met and wanted to start with an issue. George used AI to generate an outline of what we might include. Riley will create a branch to start the work. I am attaching a HTML version of that outline and Riley will put the document on GitHub.
Metadata
Metadata
Assignees
Type
Projects
- Status
Activity
rileeki commentedon Sep 23, 2026
I created the branch
761-createonboarding-documentationdirectly in this repo rather than on my own fork. This is the first time I've used my write access, and I wanted to explain in case it's a useful example for how the working group collaborates going forward.The process is still branch → PR → review before anything merges; the only change is where the branch lives. Working directly in the shared repo means we can all see the same in-progress work on this onboarding guide in one place and jump in easily, rather than everyone keeping separate copies.
I've made the first commit: @GeorgeKerscher's HTML outline converted to Markdown under docs/onboarding/. It's a skeleton/proposal only — most sections still need real content.
I think the next step is to identify which pieces already exist in helpers.md, developers.md, users.md, callers.md, etc. and link/incorporate rather than duplicate. Will bring this up at tomorrow's working group meeting — comments welcome in the meantime.
rileeki commentedon Oct 2, 2026
@GeorgeKerscher, I just pushed the change renaming docs/onboarding/README.md to docs/onboarding/onboarding_guide.md as we discussed in our call this morning. I also merged in the latest commits to main, so this branch is no longer behind. We're ready for you to pull these changes to your local branch and get started with your review!
GeorgeKerscher commentedon Oct 2, 2026
For some reason I had errors when I went to checkout main. I was being asked to delete files.
I just deleted my local clone and recloned daisy/mathcat.
I issued the command:
git switch -c 761-createonboarding-documentation --track origin/761-createonboarding-documentation
I am now on the branch. I see your file name change.
The outline is comprehensive. This leads to the next question, which what is our approach to creating content? We can use Should we make a md file for each major section and reference it from the Onboarding Guide?
Perhaps we should not make this branch a PR and plan to merge it. We should flesh out the file structure first. Perhaps write a chapter or two to see how it looks. We can then think about merging into main.
Your thoughts?