You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "wenjin272 (via GitHub)" <gi...@apache.org> on 2026/10/12 02:11:37 UTC
[I] [Doc][Umbrella] Restructure and improve documentation for 0.4 [flink-agents]
wenjin272 opened a new issue, #1225:
URL: https://github.com/apache/flink-agents/issues/1225
### Goal
Make the 0.4 documentation consistent, navigable, and usable from first setup through Agent authoring and production operations. Group the documentation review findings into coherent topic changes with shared concepts and a final cross-page review.
Related API/product work is tracked under #1055. These documentation issues describe the behavior delivered for 0.4 and coordinate with the relevant API issues; they do not require all API work to finish before documentation edits start.
### Work items
- [ ] Restructure documentation navigation and page hierarchy for 0.4
- [ ] Clarify API choices, language dimensions, and cross-language contracts
- [ ] Improve Setup and the Quickstart user journey
- [ ] Improve Agent core concepts, Actions, Events, and execution guides
- [ ] Improve Built-in ReAct Agent and Skills usage documentation
- [ ] Clarify YAML reference and Tool Use responsibilities
- [ ] Reorganize Chat Models, Chat Messages, and provider documentation
- [ ] Improve Model Routing examples and behavior reference
- [ ] Improve consistency, Action State Store, and configuration guidance
- [ ] Improve Metrics and Logging user documentation
- [ ] Add documentation and release entry points for the Coding-agent Skill
The child issues collectively cover DOC-001 through DOC-059 from the documentation review inventory. Each finding has one owner; each child body describes the task independently of that inventory.
### Delivery order and coordination
1. Prioritize Restructure documentation navigation and page hierarchy for 0.4 as a focused structural PR: navigation, page hierarchy, naming, necessary moves/splits, and URL/link preservation. Merge it early. Detailed Resource concepts belong to Improve Agent core concepts, Actions, Events, and execution guides.
2. Other topics can prepare and implement in parallel against the agreed structure, rebasing and checking links after Restructure documentation navigation and page hierarchy for 0.4 merges. Its closure is not a blanket prerequisite for starting work.
3. Clarify API choices, language dimensions, and cross-language contracts owns the shared job/Agent/component language explanation. Improve Setup and the Quickstart user journey, Improve Agent core concepts, Actions, Events, and execution guides, Clarify YAML reference and Tool Use responsibilities, and Improve consistency, Action State Store, and configuration guidance apply it in their own workflows; coordinate the agreed concepts rather than serializing all work behind Clarify API choices, language dimensions, and cross-language contracts.
4. Improve Agent core concepts, Actions, Events, and execution guides owns Resource concepts. Quickstart (Improve Setup and the Quickstart user journey), YAML (Clarify YAML reference and Tool Use responsibilities), Overview, and ReAct (Improve Built-in ReAct Agent and Skills usage documentation) must apply the same model. Clarify YAML reference and Tool Use responsibilities owns the YAML/Tool Use content boundary; Reorganize Chat Models, Chat Messages, and provider documentation coordinates provider naming across pages; Improve consistency, Action State Store, and configuration guidance owns configuration organization and coordinates option semantics with topic owners.
5. API-dependent sections are finalized against the accepted 0.4 APIs. Operations/observability edits can otherwise proceed independently; Add documentation and release entry points for the Coding-agent Skill's artifact and announcement work follows release preparation.
### Final cross-page acceptance review
Closing all children is necessary but not sufficient to close this umbrella. Review the assembled documentation as a whole:
- [ ] Agent/ReAct, Event/Action/Resource, and the three language dimensions are used consistently across Overview, Quickstart, authoring, YAML, and Deployment. In particular, confirm that Improve Setup and the Quickstart user journey and Clarify YAML reference and Tool Use responsibilities apply the Resource explanation delivered by Improve Agent core concepts, Actions, Events, and execution guides.
- [ ] Tutorials, feature guides, and references form a coherent progression, without contradictory contracts, missing steps, or unnecessary duplicated explanations.
- [ ] Java/Python/YAML examples and stated support boundaries match the actual 0.4 release APIs; API-dependent wording is finalized and unresolved compatibility claims are removed or resolved.
- [ ] Homepage, sidebar, page titles, cross-links, and preserved old URLs agree.
- [ ] Documentation build and link checks pass, and the first-job user journeys and relevant complete examples have appropriate execution validation. Record what was run and any remaining limitations.
- [ ] Version-specific migration details are in release/migration material, with necessary links from evergreen guides.
- [ ] Coding-agent Skill release/download entries are complete for the release.
Fix small findings during final review; track substantial gaps as additional child issues. Close this umbrella after this integrated review passes.
--
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: issues-unsubscribe@flink.apache.org.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] [Doc][Umbrella] Restructure and improve documentation for 0.4 [flink-agents]
Posted by "wenjin272 (via GitHub)" <gi...@apache.org>.
wenjin272 commented on issue #1225:
URL: https://github.com/apache/flink-agents/issues/1225#issuecomment-6281677461
@sangkyoonnam Thanks for the thorough checks! Yes, these fixes are in scope for 0.4 during the code freeze. As discussed in the [community sync](https://github.com/apache/flink-agents/discussions/419), we specifically reserved October 21–25 for an end-to-end review of the documentation and functionality, so this work fits well with that plan. Backporting the broken-link fixes to release-0.3 also makes sense. Please go ahead with the PRs.
I'll create an umbrella issue to track this effort. Feel free to create sub-issues under it or submit PRs directly.
--
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: issues-unsubscribe@flink.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] [Doc][Umbrella] Restructure and improve documentation for 0.4 [flink-agents]
Posted by "wenjin272 (via GitHub)" <gi...@apache.org>.
wenjin272 closed issue #1225: [Doc][Umbrella] Restructure and improve documentation for 0.4
URL: https://github.com/apache/flink-agents/issues/1225
--
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: issues-unsubscribe@flink.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [I] [Doc][Umbrella] Restructure and improve documentation for 0.4 [flink-agents]
Posted by "sangkyoonnam (via GitHub)" <gi...@apache.org>.
sangkyoonnam commented on issue #1225:
URL: https://github.com/apache/flink-agents/issues/1225#issuecomment-6274241109
@wenjin272 I'd like to run the final cross-page acceptance checks after #1234 is done and report the results here. I've started on main (`a50a8a18`).
The docs build with the pinned Hugo, and all 602 internal link targets resolve. The 34 GitHub source targets all exist on main. One problem shows up only in release docs: 17 links on six pages hard-code `blob/main` instead of using `gh_link`. In the published 0.3 docs, two such links in the Parallel LLM Quickstart now return 404 because #1271 removed those files from main.
I ran all four Quickstarts in Python and Java against a Flink 2.3.0 session cluster with `qwen3:8b`, checking the first results of each. Seven of eight produced output, the Python ReAct and YAML runs with the #1282 setting in place; Java Multiple Agents timed out twice at the example's 120-second limit, and I haven't isolated why. The runs also turned up #1281, with a Setup step for 0.4 in #1282, and showed that Setup's Apple Silicon warning applies to Python 3.11, not only 3.12.
I'd send one PR against main with the `gh_link` switch, `--branch {{< branch >}}` on the two `git clone` commands, and the Apple Silicon fix, plus a `release-0.3` backport for the broken links. Are the main-branch fixes in scope for 0.4 during the freeze?
--
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: issues-unsubscribe@flink.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org