docs: sharpen positioning and address service-locator tradeoff #280
Description
Epic: Documentation Positioning and Messaging
This is a tracking issue for improving dioxide's documentation positioning. The work has been split into smaller, focused sub-issues that can each be completed in a single PR.
Goals
- Make the value prop obvious in the first 5 seconds
- Acknowledge the
container.resolve()default-arg pattern tradeoff without apologizing for it - Create the "aha" moment for experienced devs migrating from mocks
Sub-Issues
| Issue | Title | Scope | Estimated Time |
|---|---|---|---|
| #281 | Update README tagline | Quick win | ~1 hour |
| #282 | Add Anti-goals section to README | Small | ~1-2 hours |
| #283 | Acknowledge service-locator tradeoff | Medium | ~2-3 hours |
| #284 | Create Migration from Mocks page | Larger | ~3-4 hours |
| #285 | Add FAQ: "Why not just use @patch?" | Small | ~1-2 hours |
Recommended order: #281 -> #282 -> #285 -> #283 -> #284
(Start with quick wins, end with the largest deliverable)
Acceptance Criteria
This epic is complete when all sub-issues are closed:
- docs: update README tagline for clarity #281 - README has a crisp one-liner near the top
- docs: add Anti-goals section to README #282 - README includes an "Anti-goals" section
- docs: acknowledge service-locator tradeoff in function injection #283 - Function injection section acknowledges service-locator tradeoff
- docs: create Migration from Mocks documentation page #284 - Docs include a "Migration from mocks" page with side-by-side examples
- docs: add FAQ entry "Why not just use @patch?" #285 - Docs include a short FAQ entry: "Why not just use
@patch?"
Notes
- Do NOT add request scoping as part of this issue (deferred to post-MLP per vision doc)
- Keep examples consistent with "ports and adapters" framing
- This is documentation only - no API changes
- Each sub-issue should result in exactly one PR