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/ > > > > > > > > > >
