Skip to content

REVIEW_CHECKLIST.md

Latest commit

 

History

History
396 lines (279 loc) · 9.96 KB

REVIEW_CHECKLIST.md

File metadata and controls

396 lines (279 loc) · 9.96 KB
Raw

📋 Teaching Assistant Review Checklist

Purpose: Review workshop setup documentation for accuracy, clarity, and completeness before attendee distribution.

🎯 Review Objectives

Ensure that:

  1. All setup steps are technically accurate and current
  2. Instructions are clear for developers of varying skill levels
  3. Troubleshooting covers common issues
  4. Screenshots align with current Google Cloud UI
  5. Time estimates are realistic

📚 Documents to Review

1. 0-SETUP-GUIDE.md - Google Cloud & API Key Setup

Purpose: Guide attendees through Google Cloud trial signup and Gemini API key creation

Estimated Time: 15 minutes

Review Focus:

Technical Accuracy

  • Google Cloud trial URL is correct (or placeholder is appropriate)
  • Trial credit amount is accurate ($300 as of writing)
  • OAuth consent screen steps match current GCP UI
  • API key creation flow matches Google AI Studio current UI
  • All screenshots are up-to-date

Clarity & Completeness

  • Prerequisites are clearly stated
  • Each step has clear acceptance criteria ("You should see...")
  • Security warnings are prominent
  • Navigation instructions are unambiguous
  • Naming conventions are explained

Screenshots

  • All 14 images render correctly
  • Image paths are correct (./images/1-access-credit.png, etc.)
  • Screenshots show the exact UI attendees will see
  • No sensitive information visible in screenshots

Edge Cases

  • Handles attendees with existing Google Cloud accounts
  • Addresses 2FA requirement
  • Explains what to do if credits don't appear
  • Notes about personal vs. work Google accounts

2. 0-B-SETUP-GUIDE-PROJECT.md - Project Setup & Docker

Purpose: Guide attendees through cloning, configuring, and running the workshop project

Estimated Time: 10-15 minutes

Review Focus:

Technical Accuracy

  • Git clone instructions are correct
  • .env.template to .env copy command works
  • Required .env fields match actual code requirements
  • Docker commands are correct (docker compose not docker-compose)
  • Port numbers match docker-compose.yml (80, 8000, 6379)
  • Health check endpoints are correct

Clarity & Completeness

  • File structure verification is helpful
  • .env example is complete and matches .env.template
  • Docker startup logs example matches actual output
  • Verification steps have clear success indicators
  • Links to Part 1 guide are correct

Troubleshooting

  • "401 Unauthorized" solution is accurate
  • "Connection Error" debugging steps work
  • Port conflict resolution is correct for Mac/Windows/Linux
  • Docker installation links are current
  • "Docker daemon not running" fix is clear

Pre-Workshop Checklist

  • All checklist items are testable
  • Checklist covers critical functionality
  • Order makes sense (dependencies first)

🧪 Hands-On Testing

Part 1: Google Cloud Setup

Tester: Use a fresh/test Google account

Steps:

  1. Follow 0-SETUP-GUIDE.md from start to finish
  2. Note any confusing steps or unclear language
  3. Verify all screenshots match what you see
  4. Successfully create API key
  5. Record actual time taken: _______ minutes

Issues Found:

Part 2: Project Setup

Tester: Use a clean directory (not existing clone)

Prerequisites: Must have completed Part 1

Steps:

  1. Clone repository using instructions
  2. Create .env file
  3. Add API key from Part 1
  4. Start Docker containers
  5. Verify chat UI at http://localhost
  6. Send test message and receive streaming response
  7. Check API docs at http://localhost:8000/docs
  8. Complete pre-workshop checklist
  9. Record actual time taken: _______ minutes

Issues Found:

Troubleshooting Validation

Test each troubleshooting scenario:

401 Unauthorized

  • Reproduce: Use invalid API key in .env
  • Verify: Error message matches documentation
  • Fix: Solution resolves the issue

Connection Error

  • Reproduce: Stop API container
  • Verify: UI shows "Disconnected"
  • Fix: Restart resolves issue

Port Already in Use

  • Reproduce: Start another service on port 80
  • Verify: Docker shows port conflict error
  • Fix: Commands correctly identify process

📸 Screenshot Review

Required Screenshots

Check that each image exists and is current:

  • images/1-access-credit.png - Google Cloud free trial page
  • images/2-accept-terms.jpg - Terms acceptance screen
  • images/3-credit-success.jpg - Credit success confirmation
  • images/4-create-new-cloud-project.png - New project modal
  • images/5-name-and-create-project.png - Project creation form
  • images/6-navigate-to-oauth.png - OAuth navigation
  • images/7-oauth-config.png - OAuth consent screen config
  • images/8-create-oauth-client.png - OAuth client creation
  • images/9-create-oauth-client-id.png - Client ID form
  • images/10-oauth-client-created.png - Success modal
  • images/11-ai-studio-import-project.png - AI Studio import
  • images/12-import-all-cloud-projects.png - Project selection
  • images/13-new-key-setup-modal.png - API key creation modal
  • images/14-new-entry-on-key-list.png - API key list
  • images/14-api-key-details.png - API key details modal

Screenshot Quality Checks

For each screenshot:

  • No personal information visible (emails, names, project IDs)
  • High resolution (readable text)
  • Highlights important UI elements (arrows, boxes, etc.)
  • Filename matches reference in markdown
  • File extension correct (.png or .jpg)

✍️ Content Review

Writing Quality

  • Grammar and spelling are correct
  • Tone is friendly and encouraging
  • Technical terms are explained or linked
  • Code blocks use correct syntax highlighting
  • Emoji usage is consistent and helpful (not excessive)

Accessibility

  • Links have descriptive text (not "click here")
  • Code snippets include comments
  • Screenshots have alt text or captions
  • Instructions don't rely solely on color or position

Consistency

  • Command syntax is consistent (bash blocks, etc.)
  • Terminology is used consistently
  • File paths use same format
  • Success indicators are clear (✅, 🎉, etc.)

🔗 Link Verification

External Links

Test that all external links work:

Internal Links

  • 0-B-SETUP-GUIDE-PROJECT.md references 0-SETUP-GUIDE.md correctly
  • Cross-references between sections work

🎓 Skill Level Assessment

For Beginner Developers

Background: Limited terminal/Docker experience

Can they:

  • Understand what Google Cloud is and why they need it?
  • Navigate the Google Cloud Console without getting lost?
  • Create and copy an API key successfully?
  • Use terminal commands without fear?
  • Understand what Docker is doing?
  • Debug common issues using troubleshooting section?

Confusing parts:

For Intermediate Developers

Background: Comfortable with Git, Docker basics

Can they:

  • Complete setup quickly without getting stuck?
  • Understand architecture decisions?
  • Extend the setup for their own needs?
  • Help beginners if they get stuck?

Missing advanced topics:

⏱️ Time Estimates

Part 1: Google Cloud Setup

Documentation says: 15 minutes

Actual testing:

  • Beginner: _______ minutes
  • Intermediate: _______ minutes
  • Average: _______ minutes

Recommendation:

  • Time estimate is accurate
  • Increase to: _______ minutes
  • Decrease to: _______ minutes

Part 2: Project Setup

Documentation says: 10-15 minutes

Actual testing:

  • Beginner: _______ minutes
  • Intermediate: _______ minutes
  • Average: _______ minutes (including first-time Docker image download)

Recommendation:

  • Time estimate is accurate
  • Increase to: _______ minutes
  • Decrease to: _______ minutes

🐛 Common Issues Discovered

During Testing

Document any issues found:

  1. Issue:

    • Step:
    • Expected:
    • Actual:
    • Severity: Critical / Major / Minor
    • Suggested Fix:

  2. Issue:

    • Step:
    • Expected:
    • Actual:
    • Severity: Critical / Major / Minor
    • Suggested Fix:

💡 Suggestions for Improvement

Content Additions

What's missing that would help attendees?

Clarity Improvements

Which sections need better explanations?

Additional Troubleshooting

What other errors might attendees encounter?

✅ Final Approval

Reviewer Information

  • Reviewer Name: _______________________
  • Date Reviewed: _______________________
  • Testing Environment:
    • OS: _______________________
    • Docker Version: _______________________
    • Browser: _______________________

Sign-Off

  • All technical steps are accurate
  • All links work and are current
  • All screenshots are correct and up-to-date
  • Troubleshooting section is comprehensive
  • Time estimates are realistic
  • Suitable for target audience
  • APPROVED FOR ATTENDEE DISTRIBUTION

Blockers (if not approved)

Critical issues that must be fixed: 1. 2.

Recommended improvements: 1. 2.

📧 Feedback Submission

Submit feedback to: [Instructor Email]

Feedback Deadline: [Date]

Questions or Concerns:

  • Use workshop Slack channel: #workshop-prep
  • Email instructor directly
  • Schedule office hours

Thank you for helping make this workshop successful! 🙏