docs: full documentation restructure and rewrite#173
Merged
Conversation
Documents architecture, dev loop, public API surface, behavioral nuances, and coding principles — rewritten from actual source rather than the stale POC that /init had on hand.
Reorganise all docs pages into a clearer 8-section hierarchy: Introduction, Getting Started, Jobs (guide), Queues (guide), Production, Recipes, API Reference, and Resources. File moves preserve git history; all internal links updated to match new paths; VitePress config updated with new sidebar, nav, and rewrites for old URLs.
Homepage hero leads with the core value prop. Why Sidequest page explains the Redis overhead problem, transactional enqueue advantage, and target persona. How It Works page covers the two-process architecture, piscina thread pool, atomic job claiming, and queue model with prose and diagrams.
…ueue, Oban Feature matrix sourced from official docs and GitHub repos (as of May 2026). Per-library sections explain where each alternative wins and where Sidequest wins, with explicit caveats. No benchmarks — performance claims omitted.
Deployment guide covers embedded vs. separate-worker topology, environment variables, PM2/systemd/Docker examples, multi-instance cron deduplication, dashboard security, connection pool sizing, and graceful shutdown notes. Also corrects the comparison table: transactional enqueue is not yet a first-class JobBuilder API — marked as roadmap item with an honest footnote.
Five recipes with real, runnable code: - Emails: basic job, deduplication, scheduled digest, backoff, fail() on hard bounce - Job chaining: sequential steps, fan-out pattern, passing data between steps - Rate limiting: queue concurrency, snooze on 429, availableAt spacing - Scheduled reports: daily/weekly/monthly cron, multi-instance deduplication, on-demand trigger - Standalone dashboard: SidequestDashboard usage, separate process topology
Merge guide/jobs/run-method.md and convenience-methods.md into a single guide/jobs/running.md with a runtime-metadata table, method reference (complete/fail/retry/snooze), decision table, and Next footer. Add Next footers to installation.md and class.md. Fix all internal links and add VitePress rewrites for the old page URLs.
- Restore homepage to original content (only update action links) - Remove Alternatives comparison page - Remove rate-limiting recipe (not a Sidequest feature) - Rename sidebar entry to "Execution and Control" - Rewrite running.md with flow control framing - Remove transactional enqueue roadmap claim from why.md
GiovaniGuizzo
approved these changes
May 3, 2026
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
2 participants
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
Test plan
yarn workspace @sidequest/docs buildpasses with zero dead linksyarn workspace @sidequest/docs dev)/jobs/lifecycle→/guide/jobs/lifecycle)