Hi all, Thanks for the feedback! Let me go through them one-by-one:
> I like the way that the data types are currently documented showing how each are implemented in SQL and the APIs, this is useful for Flink contributors.Is there a way to keep this view in the structure somewhere maybe in a contributor section? The Data Types content (including the SQL/Java/Scala type mappings) is moving to SQL Reference, not being removed. The contributor-friendly view will be preserved. We could add add a cross-link from Table API documentation to ensure discoverability from both entry points. > You mention the Diátaxis documentation framework - I wondered about the how-to guides (task-oriented), and the reference material. Do we think there is no how to guides? That's correct indeed. The current Flink docs are primarily tutorials and reference material. True task-oriented how-to guides are largely missing or scattered across blog posts. Since this is mostly a restructuring of existing content, it won't immediately solve that problem. I'd rather first focus on this effort and the others that are currently out of scope of the FLIP, and then work on this one. > In the past I have used snippets for documentation that is duplicated, do we plan to use something like that for the duplicated content in SQL and table APIs? So we only have information authored once? Can you give an example of where you used snippets? Hugo does support content reuse via shortcodes and partials, so when needed we can leverage it. For most cases, cross-linking may be simpler to maintain. > One additional thing that may be worth evaluating changing is the Connectors section. Absolutely. I intentionally scoped Connectors restructuring as a separate follow-up FLIP (noted in the Future Work section), because it requires a bit more reorganization given the docs are in the external connector repos too and I have some additional ideas too. The vision is to organize by system (Kafka, JDBC, etc.) with tabs showing SQL/Table API/DataStream usage where applicable, plus a dedicated Formats subsection with proper context. > 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. Good suggestion. I'll add a link or redirect under "Flink APIs → Table API → Functions" pointing to "Flink SQL → Functions → Built-in Functions". This follows the same pattern as Data Types, by maintaining content in one location, cross-link from related sections to ensure discoverability without duplication. > 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? Good question. The intended distinction is like this: - Learn Flink: Learning-oriented tutorials where you follow along and build something. The focus is on either snippet-based or guided, hands-on learning paths. - Concepts: Explanation-oriented content about foundational ideas and mental models. The focus is on understanding how things work. The boundary isn't perfectly clean in the current proposal - for example, "Streaming Analytics" in Learn Flink has conceptual elements. The guiding principle is: if content is primarily "follow these steps to learn X", it belongs in Learn Flink. If it's primarily "here's how X works under the hood", it belongs in Concepts. We could refine this further, but the core distinction is (either snippet or hands-on) learning vs. theoretical understanding. Best regards, Martijn On Thu, Jan 8, 2026 at 4:58 AM Xintong Song <[email protected]> wrote: > 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/ > > >
