Split README into per-workflow docs/ pages#87
Merged
Conversation
The README had grown to ~900 lines with a per-task section for each of
22 tasks, making it hard to find the workflow you wanted. This refactor
splits the per-task documentation into five workflow-scoped pages under
docs/, plus a separate docs/installation.md for first-time setup. The
new README is ~80 lines: Overview, a one-line Setup pointer, the Usage
cheat-sheet, and a workflow index linking to docs/.
New layout:
- docs/installation.md Canvas API token + Python deps + Ollama
- docs/peer-instruction-and-bonus create-pairs, award-bonus[-{partner,retake}-only]
- docs/quiz-followup-questions get-quiz-questions, generate-follow-up-questions,
send-quiz-reminder, send-follow-up-question,
assess-replies, send-follow-up-assessments
- docs/media-recording-checkins create-media-recording-assignment,
get-media-recordings, analyze-media-recordings
- docs/cross-workflow prep-class-digest
- docs/misc-tasks create-quiz, export-anon-data, get-activity,
get-quiz-submission-events, get-conversations,
delete-old-conversations, get-gradebook,
get-roster
Each workflow doc opens with a summary table, a "Back to main README"
link, and an end-to-end workflow walkthrough where the chain spans
multiple tasks.
Polish in the same pass:
- Per-task headings simplified from `## task-name — Long Description`
to `## \`task-name\`` with a one-line italic tagline below, so anchors
collapse from `#task-name--long-description` to clean `#task-name`.
- Standardized per-task structure: tagline, description, "Before
running:" prereqs, Files table, then flag notes.
- Trimmed per-task "Typical workflow:" subsections that duplicated the
doc-level workflow overview.
- Added an ASCII data-flow diagram to the quiz-follow-up doc since that
workflow has six chained tasks and five derived CSVs.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/, plus a separatedocs/installation.mdfor first-time setup.## task-nameheadings (clean#task-nameanchors), standardized per-task structure (tagline → description → "Before running:" → Files table), trimmed duplicate "Typical workflow:" subsections, and added an ASCII data-flow diagram to the quiz-follow-up doc.New layout
docs/installation.mddocs/peer-instruction-and-bonus.mdcreate-pairs,award-bonus,award-bonus-partner-only,award-bonus-retake-onlydocs/quiz-followup-questions.mdget-quiz-questions,generate-follow-up-questions,send-quiz-reminder,send-follow-up-question,assess-replies,send-follow-up-assessmentsdocs/media-recording-checkins.mdcreate-media-recording-assignment,get-media-recordings,analyze-media-recordingsdocs/cross-workflow.mdprep-class-digestdocs/misc-tasks.mdcreate-quiz,export-anon-data,get-activity,get-quiz-submission-events,get-conversations,delete-old-conversations,get-gradebook,get-rosterTest plan
README.md, click each of the 5 workflow links + the Setup link → all 6 docs render and the "Back to main README" link returns to the README.docs/cross-workflow.md, click the inline cross-doc links toanalyze-media-recordings,get-quiz-submission-events,get-quiz-questions,assess-replies,get-media-recordings→ each anchor jumps to the correct task section.docs/peer-instruction-and-bonus.md, click any of the threeget-quiz-submission-eventsreferences → jumps to misc-tasks.md.docs/quiz-followup-questions.mdanddocs/misc-tasks.md, click eachOllama setuplink → jumps todocs/installation.md#ollama-setup-optional.python -m pytest test_canvigator.py -qstill passes (it does locally; this PR is docs-only).python canvigator.py --helpandpython canvigator.py <task> --helpare unchanged.🤖 Generated with Claude Code