Skip to content

feat: Restructure JavaScript cron monitoring documentation #14407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 8 commits into
base: master
Choose a base branch
from

Conversation

smeubank
Copy link
Member

@smeubank smeubank commented Jul 18, 2025

experiment: included in this PR are the .cursor folder changes and product docs, all generated with AI, to experiment with docs repo changes

Preview: here

  • Transform overwhelming 275-line single page into focused method picker

  • Create separate pages for each integration approach:

    • UI Setup: Two-step process (create monitor + add notification code)
    • Automatic: Auto-instrumentation for node-cron/cron/node-schedule
    • Manual: Full SDK control with custom error handling
    • Advanced: Programmatic monitor management for CI/CD
  • Add comprehensive PRFAQ addressing real user confusion

  • Include decision framework to eliminate choice paralysis

  • Add redirect alerts for backward compatibility

  • Enhance troubleshooting with issue resolution

  • Add Cursor project rules and feature development workflow

Addresses user feedback about confusing UI flow and overwhelming docs that showed 4+ methods without clear guidance on which to use.

- Transform overwhelming 275-line single page into focused method picker
- Create separate pages for each integration approach:
  * UI Setup: Two-step process (create monitor + add notification code)
  * Automatic: Auto-instrumentation for node-cron/cron/node-schedule
  * Manual: Full SDK control with custom error handling
  * Advanced: Programmatic monitor management for CI/CD

- Add comprehensive PRFAQ addressing real user confusion
- Include decision framework to eliminate choice paralysis
- Add redirect alerts for backward compatibility
- Enhance troubleshooting with issue resolution

- Add Cursor project rules and feature development workflow

Addresses user feedback about confusing UI flow and overwhelming docs
that showed 4+ methods without clear guidance on which to use.
Copy link

vercel bot commented Jul 18, 2025

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Comments Updated (UTC)
develop-docs ✅ Ready (Inspect) Visit Preview 💬 Add feedback Jul 19, 2025 8:47am
sentry-docs ✅ Ready (Inspect) Visit Preview 💬 Add feedback Jul 19, 2025 8:47am

Copy link

codecov bot commented Jul 18, 2025

Bundle Report

Changes will increase total bundle size by 9.25kB (0.04%) ⬆️. This is within the configured threshold ✅

Detailed changes
Bundle name Size Change
sentry-docs-client-array-push 9.84MB -6 bytes (-0.0%) ⬇️
sentry-docs-server-cjs 11.98MB 9.26kB (0.08%) ⬆️

Affected Assets, Files, and Routes:

view changes for bundle: sentry-docs-server-cjs

Assets Changed:

Asset Name Size Change Total Size Change (%)
1729.js -3 bytes 1.67MB -0.0%
../instrumentation.js -3 bytes 999.78kB -0.0%
9523.js -3 bytes 975.72kB -0.0%
../app/[[...path]]/page.js.nft.json 3.09kB 723.28kB 0.43%
../app/platform-redirect/page.js.nft.json 3.09kB 723.19kB 0.43%
../app/sitemap.xml/route.js.nft.json 3.09kB 721.16kB 0.43%
view changes for bundle: sentry-docs-client-array-push

Assets Changed:

Asset Name Size Change Total Size Change (%)
static/chunks/pages/_app-*.js -3 bytes 881.08kB -0.0%
static/chunks/1831-*.js -3 bytes 423.46kB -0.0%
server/middleware-*.js 5.55kB 6.55kB 555.3% ⚠️
server/middleware-*.js -5.55kB 1.0kB -84.74%
static/qu_pt7-*.js (New) 684 bytes 684 bytes 100.0% 🚀
static/qu_pt7-*.js (New) 77 bytes 77 bytes 100.0% 🚀
static/Gm9RPVd3HkZFQIV_PQUoO/_buildManifest.js (Deleted) -684 bytes 0 bytes -100.0% 🗑️
static/Gm9RPVd3HkZFQIV_PQUoO/_ssgManifest.js (Deleted) -77 bytes 0 bytes -100.0% 🗑️

- Convert <Tabs>/<Tab> components to {tabTitle:...} syntax
- Resolves Vercel build error: 'Expected component Tab to be defined'
- Fixes prerender error on /platforms/javascript/guides/hapi/crons/advanced
- Simplify crons/index.mdx: Remove heavy card components, change 'easiest' to 'recommended'
- Add PRFAQ open questions: What's the bare minimum for working cron monitoring?
- Clarify UI-first vs code-first approach and define 'easiest' vs 'most complete'
- Ready for team review on product strategy and simplified UX
- Add comprehensive platform checklist for cron docs improvements
- Update product docs with real implementation details and success metrics
- Restructure .cursor/rules for language-agnostic documentation
- Establish content strategy framework for cross-platform consistency
- Create scope matrix to prevent content duplication
- Document proven patterns from JavaScript platform success (60% content reduction)

This framework enables systematic documentation improvements across all Sentry platforms while maintaining consistency and reducing maintenance overhead.
Core documentation implementation:
- Simplified main cron index page with clear method categorization
- Created dedicated pages for each manual method (job-monitoring, check-ins, heartbeat, upserting)
- Added automatic integration pages for cron-library, node-cron, node-schedule
- Converted troubleshooting to concise FAQ format (4 key issues)
- Removed manual.mdx (redundant with individual method pages)
- Added shared cron configuration properties include

Content improvements:
- 60% reduction in average page length (200+ lines → 50-80 lines)
- Essential-first structure: purpose → when to use → quick example → links
- Eliminated duplicate content and verbose explanations
- Working, tested code examples for all methods
- Progressive disclosure (advanced topics linked, not inline)

Updated feature documentation:
- Enhanced PRD and PRFAQ with real implementation learnings
- Documented proven patterns for cross-platform application

This demonstrates the unified documentation framework in action on the JavaScript platform, serving as the reference implementation for other platforms.
Move PLATFORM-CRON-DOCS-CHECKLIST.md from project root to the 005-unified-cron-monitoring-experience feature folder where it logically belongs.

This keeps all related documentation and implementation guidance together in one cohesive feature package.
…ssing JS platforms

Corrections:
- Clarify that Phase 1 completed Next.js, SvelteKit, Remix, NestJS (not base Node.js)
- Add Node.js base patterns as completed (established during framework work)

Additions:
- Add missing JavaScript platforms: Koa, Hapi, Deno, Bun
- Add Express for review (may have existing patterns)

Special Requirements:
- Add detailed Next.js + Vercel integration requirements
- Specify automatic-vercel.mdx page creation
- Include content structure from existing Vercel documentation
- Note Pages Router vs App Router limitations

Updated Rollout Schedule:
- Phase 1: Complete remaining JavaScript platforms first
- Phases 2-3: Continue with Python, PHP, Java, etc.
- Add Next.js Vercel automatic integration page
- Create comprehensive Next.js crons main page with proper navigation
- Simplify Vercel integration content to be concise and actionable
- Update platform checklist to reflect Next.js completion
- Revert Nuxt changes (missing sub-pages, moved back to pending)
- Remove Nuxt from supported platforms in common JS crons

Next.js now has complete cron monitoring documentation including:
- Main crons page with all setup methods
- Dedicated Vercel automatic integration page
- Proper cross-references and navigation structure
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant