> - 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.
Thanks for the explanation. Sounds good to me. Best, Xintong On Fri, Jan 9, 2026 at 8:04 AM David Anderson <[email protected]> wrote: > Martijn, thanks for taking this on. This looks great. > > I think it's smart to limit the scope to something manageable and concrete > (as you've done). > > Maybe we can add a couple more bullet points to the Future Work section. A > reorg of the Deployment and Operations sections could be listed there, > along with a reorg of some of the explanatory and learning content to > better follow the diataxis model. I have some ideas, and look forward to > helping out there in the future. > > David > > On Thu, Jan 8, 2026 at 7:33 AM Ryan van Huuksloot via dev < > [email protected]> wrote: > > > >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/ > > > > > > > > > > > > > > >
