Skip to content

docs: reorganize and consolidate documentation#342

Merged
ngjunsiang merged 1 commit intoweeklyfrom
docs/update-docs
Feb 3, 2026
Merged

docs: reorganize and consolidate documentation#342
ngjunsiang merged 1 commit intoweeklyfrom
docs/update-docs

Conversation

@nycomp
Copy link
Contributor

@nycomp nycomp commented Feb 3, 2026

Summary

This PR reorganizes the Campus documentation to eliminate duplication and improve clarity for both human and AI contributors.

Changes

File Structure

  • Move docs/AGENTS.mdAGENTS.md (project root for better discoverability)
  • Create docs/TESTING-GUIDE.md (merges content from deleted docs/test-plan.md)
  • Delete docs/test-plan.md (content merged into TESTING-GUIDE.md)

Document Refactoring

Each document now has a single, well-defined purpose:

Document Purpose
AGENTS.md Quick reference for humans and AI agents (Poetry, run_tests.py, critical reminders)
GETTING-STARTED.md Role-based navigation + installation only
CONTRIBUTING.md Workflow/process (branching, PRs) + code review checklist
STYLE-GUIDE.md Coding standards + import conventions
development-guidelines.md Architecture patterns (starts with Storage-Model-Resources) + doc standards
TESTING-GUIDE.md Complete testing guide with decision tree
PACKAGING.md Build/distribution only (removed workflow content)

Key Improvements

  1. No duplication - Import conventions live only in STYLE-GUIDE; doc standards only in development-guidelines; code review only in CONTRIBUTING
  2. Better flow - development-guidelines now starts with foundational Storage-Model-Resources pattern
  3. Accurate examples - Resources layer properly documented with actual Resource class patterns; Routes layer shows real usage
  4. Test decision tree - Added to help developers choose the right test type
  5. Fixes - README.md Quick Start commands corrected; broken emoji rendering in architecture.md fixed

Test Plan

  • All documentation cross-references checked and updated
  • No broken links within docs
  • AGENTS.md moved to project root
  • TESTING-GUIDE.md created from test-plan.md + tests/README.md content
  • All files updated with consistent formatting

🤖 Generated with Claude Code

- Move AGENTS.md to project root for better discoverability
- Create TESTING-GUIDE.md merging test-plan.md content
- Refactor docs by purpose to eliminate duplication:
  - GETTING-STARTED: Navigation + installation only
  - CONTRIBUTING: Workflow/process + code review checklist
  - STYLE-GUIDE: Coding standards + import conventions
  - development-guidelines: Architecture patterns + doc standards
  - TESTING-GUIDE: Complete testing guide with decision tree
  - PACKAGING: Build/distribution only (removed workflow)
- Fix README.md Quick Start command syntax
- Fix broken emoji rendering in architecture.md
- Update all cross-references to point to correct files

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@ngjunsiang ngjunsiang merged commit 3765c53 into weekly Feb 3, 2026
4 checks passed
@ngjunsiang ngjunsiang deleted the docs/update-docs branch February 3, 2026 06:11
@nycomp nycomp added the documentation Improvements or additions to documentation label Feb 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants