Hi Martijn, Big +1, the new structure looks more clear. I have a small question, "User-defined Sources & Sinks" seems to define the source & sink for connectors, shall we move it in Connectors?
Best regards, Zhe Wang Martijn Visser <[email protected]> 于2026年1月12日周一 21:18写道： > I've included in the FLIP that the docs contribution guide should be > updated, so that it's clear what should go into Learn Flink vs Concepts. > > I'm planning to open a vote on this later this week, so that there's still > some time for other developers or users to chip-in if they want to. > > Best regards, > > Martijn > > On Fri, Jan 9, 2026 at 2:14 AM Xintong Song <[email protected]> wrote: > > > > - 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/ > > > > > > > > > > > > > > > > > > > > > > > > > > > >
