Thanks for putting this together, Martijn. I really like the proposed structure.
I think it would make sense to link out to the existing PyDocs site( https://nightlies.apache.org/flink/flink-docs-release-2.2/api/python/) as a sub tab under the proposed `Flink APIs` tab and we can move the documentation in the current Python sub tab to this single source. This would loosely follow how PySpark and PyIcergerg docs are organized. PyIceberg Specific Documentation [image: Screenshot 2026-01-07 at 2.10.40 PM.png] Iceberg Main Documentation [image: Screenshot 2026-01-07 at 2.10.25 PM.png] PySpark Specific Documentation [image: Screenshot 2026-01-07 at 1.30.27 PM.png] Spark Main Documentation [image: Screenshot 2026-01-07 at 1.30.16 PM.png] I am happy to contribute to the restructuring of the Python documentation! On Wed, Jan 7, 2026 at 7:26 AM Ryan van Huuksloot via dev < [email protected]> wrote: > Hi Martijn, > > +1 overall. I like the overall new structure better. > > One additional thing that may be worth evaluating changing > is the Connectors section. A few things come to mind: > - Hybrid Source under Datastream Connectors. It is more of a concept. > - Hive under Table Connectors blurs the line between a connector, catalog > and built in functions. > - The "Connectors" header, from my perspective, should represent just the > Data Source and Data Sink connectors. We've colocated anything that is an > external connection under Connectors. I wonder if we need a different high > level name so things like "Models" make more sense under that header. > - Similar to above, the "Formats" under the Connectors feel out of place. I > don't have a recommendation here but they seem to be put there because they > are coupled to Connectors but there isn't much there to understand why they > are there unless you know what Formats are and how they are used. > - The "Overview" in each of the Formats is out of date. > - The "Download" in Table Connectors is out of date - and could likely be > removed. > > Ryan van Huuksloot > Staff Engineer, Infrastructure | Streaming Platform > [image: Shopify] > <https://www.shopify.com/?utm_medium=salessignatures&utm_source=hs_email> > > > On Wed, Jan 7, 2026 at 6:20 AM Leonard Xu <[email protected]> wrote: > > > +1 from my side, the new structure looks good and compatibility for > > existing urls makes sense to me, thanks Martijn for improving our > > documentations. > > > > Best, > > Leonard > > > > > 2026 1月 7 18:01，Martijn Visser <[email protected]> 写道： > > > > > > 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/ > > > > >
