>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.
Perfect, I missed that. Sounds like a good plan. Thanks for leading this effort! Ryan van Huuksloot Staff Engineer, Infrastructure | Streaming Platform [image: Shopify] <https://www.shopify.com/?utm_medium=salessignatures&utm_source=hs_email> On Thu, Jan 8, 2026 at 10:14 AM Martijn Visser <[email protected]> wrote: > 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/ > > > > > >
