[Docs] Enhance docs

[ryankert01]

• enhance current docs
  • update https://mahout.apache.org/docs/next/qdp/readers
  • update https://mahout.apache.org/docs/next/qdp/getting-started
• add migration docs
• looking forward to add more examples

[bearomorphism]

Hey @ryankert01 — passing through this issue and trying to figure out what's still actionable. The original description is intentionally a tracker, but it''s gotten hard to tell what''s left after the recent docs PRs landed. Here''s my read of the current state — please correct anything I got wrong:

Status by bullet

Original bullet	Status
update https://mahout.apache.org/docs/next/qdp/getting-started	✅ done in #1290
update https://mahout.apache.org/docs/next/qdp/readers	⚠️ partially — see below
(related) phase / iqp encoding docs	✅ done in #1286
(related) python-api sync	✅ done in #1287
add migration docs	❌ not started; scope unclear (qdp version-to-version? jekyll→docusaurus is in docs/adr/001-…)
add more examples	❌ open-ended; assume you''re driving this

Remaining concrete defects on the readers bullet

(A) qdp/docs/readers/README.md — two ../ADDING_INPUT_FORMATS.md links at lines 137 and 221 are broken (file never existed). lychee.toml carries an explicit exclusion with # TODO: fix the links in this file because of these. Verified locally:

$ lychee qdp/docs/readers/README.md
[ERROR] file:///…/qdp/docs/ADDING_INPUT_FORMATS.md (at 137:5) | File not found
[ERROR] file:///…/qdp/docs/ADDING_INPUT_FORMATS.md (at 221:25) | File not found
🔍 2 Total ✅ 0 OK 🚫 2 Errors

(B) docs/qdp/readers.md (the published page in the issue) already softened the prose link to ADDING_INPUT_FORMATS.md (TODO) (lines 142, 226), but still has a "File Organization" tree at line 171 referencing the non-existent file. It''s also a near-duplicate of qdp/docs/readers/README.md with slightly different content — worth deciding whether one should canonicalize and the other should include or just link.

Suggestions

• Break this issue into trackable sub-tasks. E.g. [Docs] qdp/readers cleanup, [Docs] write ADDING_INPUT_FORMATS.md (or decide to drop the placeholder), [Docs] qdp migration guide. The current scope makes it hard to attract drive-by contributors.
• Define what "migration docs" means — qumat 0.5→0.6 user-facing migration, or the engine-internals migration plan?

Offer

Happy to take (A) above (orthogonal infra fix: rewrite the dead ../ADDING_INPUT_FORMATS.md refs in qdp/docs/readers/README.md to a (TODO) placeholder mirroring docs/qdp/readers.md, and drop the lychee.toml exclusion). Same pattern I just used in #1305 for the contributor docs. I''ll leave the content rewrite of docs/qdp/readers.md, the ADDING_INPUT_FORMATS.md content, and the migration docs to you unless you''d rather hand off any of those.

Let me know which of those (if any) you want me to pick up.

---

Edit: re-labelled the two defects as (A) / (B) instead of 1. / 2. because GitHub was autolinking my reference to "#1" as PR #1.

[bearomorphism]

Just had AI to re-investigate this issue and updated the status in the above comment.

[ryankert01]

add some context: The docs is user oriented and want to help user understand our thing, so anything that helps user engage can be added.