andygrove opened a new pull request, #5196:
URL: https://github.com/apache/datafusion-comet/pull/5196
## Which issue does this PR close?
Closes #.
## Rationale for this change
We get the same handful of user questions repeatedly, and while most of the
answers already exist in the docs, they are spread across the tuning guide, the
plan guide, the compatibility guide, the roadmap, and the Gluten comparison. A
new user with a question phrased in their own words has no entry point to them.
Looking through GitHub discussions and issues for the recurring themes,
these came up most:
| Source | Already answered somewhere? |
| --- | --- |
| #3199, #1084 — benchmarked and Spark was faster / no speedup | scattered
across tuning + plan guides |
| #5001 — native OOM on large joins/distinct where Spark succeeds | partly
in the tuning guide's memory section |
| #1018, #4648, #174 — plans for Delta Lake / the data lake ecosystem |
roadmap, but that lives under the *contributor* guide |
| #3043 — Spark 3.3 / JDK 8 support | implied by the supported-versions
table, never stated as a "no" |
| #1196 — does Comet use SIMD | nowhere |
| #994 — comparison with Gluten | yes, `about/gluten_comparison.md` |
| #1014 — jars for Apple Silicon | yes, installation guide |
## What changes are included in this PR?
Adds `docs/source/faq.md` with 15 questions in four sections (Getting
Started, Performance, Compatibility and Support, Project and Community), and
links it from the top-level toctree in `index.md` and from the homepage
"Getting Started" blurb.
Two things worth calling out for review:
**The page is a routing layer, not a new source of truth.** Every answer is
a few sentences that ends in a link into the relevant guide. Nothing is
documented only here. That is the property that stops the page drifting out of
sync with the versioned user guide, and I'd suggest we keep it as the rule for
future additions.
**The page is unversioned, and links into `user-guide/latest`.** Several
answers are roadmap- and project-level ("do you plan to support Delta Lake?",
"what's coming next?"), which would go stale if frozen into a per-release
snapshot, and versioning the page would mean maintaining N copies of it.
Linking to `latest` follows what the homepage CTAs and `gluten_comparison.md`
already do — but note `latest` is the development snapshot rather than the
current stable release, so the FAQ points users slightly ahead of what most of
them are running. I followed the existing convention rather than diverging, and
said so in the page intro. Happy to change it if we'd rather unversioned pages
targeted stable, though that feels like a separate site-wide decision.
On the Spark/JDK question specifically: the JDK 11 and Spark 3.4 deprecation
is already documented in three places (`installation.md`,
`compatibility/spark-versions.md`, and `versioning_policy.md`), so the FAQ
restates it as a warning admonition and links out rather than becoming a fourth
place to keep in sync.
## How are these changes tested?
Docs only, no code changes.
- Verified all 14 relative file links resolve and all 10 cross-file heading
anchors match a real heading in the target file.
- `npx prettier "**/*.md"` reports both files clean.
I was not able to build the docs locally — `docs/requirements.txt` fails to
install in my environment — so the toctree entry is unexercised until CI builds
the site. Worth a look at the rendered output before this comes out of draft.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
