Docs: Lead performance/cost table with speculative write costs (the default)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 6h 51m
- Merged PRs (30d)
- 104
Description
Problem
The performance documentation shows both normal path and speculative write costs, but doesn't emphasize that speculative writes are enabled by default. A reader scanning the cost table sees the normal path first and assumes that's the default cost.
This led to a concrete misunderstanding: estimating 10M non-cascade calls at $7.50/month (normal path: 1 RCU + 1 WCU per call) when the actual default cost is ~$6.88/month (speculative: 0 RCU + 1 WCU per call, with ~5% fallback).
Suggested Changes
-
Reorder the cost table to lead with speculative write costs since they are the default behavior.
-
Add a callout at the top of the performance section:
> **Note:** Speculative writes are enabled by default. The costs
> below reflect the default configuration. To use the normal
> read-before-write path, set `speculative_writes=False`.
- Add a quick-reference cost summary for common scales:
| Scale | Non-Cascade (default) | Cascade (default) |
|---|---|---|
| 1M calls/month | ~$0.69 | ~$1.29 |
| 10M calls/month | ~$6.88 | ~$12.85 |
| 100M calls/month | ~$68.80 | ~$128.50 |
(Assuming ~95% speculative hit rate, on-demand pricing)
Why This Matters
Cost estimation is a key factor when evaluating rate limiting solutions. If the docs lead with the more expensive path, users may overestimate costs and choose a different solution unnecessarily.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the performance documentation and its existing cost table, then review how normal and speculative write paths are currently presented. Done means the table leads with speculative writes, the default behavior is called out, and the requested quick-reference summary and configuration note are included.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100