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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
