Big +1! Thanks for putting this together, Martijn. This sounds great. One quick question, what are the different purposes of Learn Flink and Concepts. It seems Learn Flink also contains some api-agnostic concepts, as well as introductions to different api sets. What is the boundary?
Best, Xintong On Thu, Jan 8, 2026 at 10:43 AM dylanhz <[email protected]> wrote: > Hi Martin, > > > This proposal looks great to me. I think the new structure is well > organized and easy to understand. > > > I have only one small suggestion: > We might need a "Built-in Functions" section under "Flink APIs - Table API > - Functions" that redirects to "Flink SQL - Functions - Built-in > Functions". This would help users navigate more easily. > > > > -- > > Best regards, > dylanhz > > > > At 2026-01-07 18:01:32, "Martijn Visser" <[email protected]> wrote: > >Hi everyone, > > > >I'd like to start a discussion on FLIP-561 [1] to restructure the Apache > >Flink documentation to improve discoverability and usability of them. The > >Flink documentation has evolved organically over many years. While > >comprehensive, users face several navigation challenges: > > > >- The distinction between "Try Flink", "Learn Flink", and "Concepts" is > >unclear (these blur the Diátaxis categories of tutorials, explanation, and > >reference) > >- SQL is bundled with Table API, forcing SQL-only users through > >programmatic content > >- Streaming concepts like Dynamic Tables are buried in Table API, though > >they are general relational streaming concepts > >- Python documentation duplicates the structure of both Table API and > >DataStream API > >- Connector documentation is fragmented by API rather than by system > > > >This FLIP also refers to previously discussed and/or voted on FLIP-60 [2] > >and FLIP-541 [3] > > > >The FLIP contains the new proposed information architecture and a couple > of > >screenshots from my local changes. You can also use this live website [4] > >that contains mostly the refactored menu structure, content that has been > >moved to a new location and some new content (like First Steps). > > > >I'd appreciate feedback on the proposed structure and rest of the FLIP. > > > >Thanks, > > > >Martijn > > > >[1] > > > https://cwiki.apache.org/confluence/display/FLINK/FLIP-561%3A+Restructure+Flink+documentation > >[2] > > > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=127405685 > >[3] > > > https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=378473217 > >[4] > > > https://apache-flink-doc-refactoring.netlify.app/docs/getting-started/local_installation/ >
