Hi, I agree this sounds like a good idea. Some thoughts (not show stoppers - but I wanted to share):
I like the way that the data types are currently documented [1] 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? You mention the Diátaxis documentation framework<https://diataxis.fr/> - I wondered about the how-to guides (task-oriented), and the reference material. Do we think there is no how to guides? 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? [1]https://nightlies.apache.org/flink/flink-docs-release-2.2/docs/dev/table/types/ Kind regards, David. From: Rion Williams <[email protected]> Date: Wednesday, 7 January 2026 at 12:04 To: [email protected] <[email protected]> Subject: [EXTERNAL] Re: [DISCUSS] FLIP-561: Restructure Flink documentation This Message Is From an Untrusted Sender You have not previously corresponded with this sender. Report Suspicious<https://us-phishalarm-ewt.proofpoint.com/EWT/v1/AdhS1Rd-!9_FVM1i8MyHVtRbX4KWBko41WO_lJ-CjQ7ezmVhcDkH1VhZBHBA27diuIpptfvjmXTTOg0NQX18AKZDnl8JUilkiMt3Lst_UdoTv$> +1, this seems like a great idea! Thanks for putting it together Martijn! On Jan 7, 2026, at 4:03 AM, 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/ Unless otherwise stated above: IBM United Kingdom Limited Registered in England and Wales with number 741598 Registered office: Building C, IBM Hursley Office, Hursley Park Road, Winchester, Hampshire SO21 2JN
