Hi Jark, Thank you for joining the discussion. I am totally fine with the "Language Tabs". Would be good to hear what the PyFlink community thinks, because the Python Documentation is the biggest exception to the "Language Tabs" approach.
@Jark Wu <imj...@gmail.com>: Do you agree that SQL should be separate from Table API/DataStream API in either way? I think SQL does neither fit into the "Language Tabs" nor "Language First". Cheers, Konstantin On Wed, Mar 23, 2022 at 9:17 AM Jark Wu <imj...@gmail.com> wrote: > Hi Konstantin, > > Thanks for starting this discussion. > > From my perspective, I prefer the "Language Tabs" approach. > But maybe we can improve the tabs to move to the sidebar or top menu, > which allows users to first decide on their language and then the API. > IMO, programming languages are just like spoken languages which can be > picked in the sidebar. > What I want to avoid is the duplicate docs and in-complete features in a > specific language. > "Language First" may confuse users about what is and where to find the > complete features provided by flink. > > For example, there are a lot of duplications in the "Window" pages[1] and > "Python Window" pages[2]. > And users can't have a complete overview of Flink's window mechanism from > the Python API part. > Users have to go through the Java/Scala DataStream API first to build the > overall knowledge, > and then to read the Python API part. > > > * Second, most of the Flink Documentation currently is using a "Language > Tabs" approach, but this might become obsolete in the long-term anyway as > we move more and more in a Scala-free direction. > > The Scala-free direction means users can pick arbitrary Scala versions, not > drop the Scala API. > So the "Language Tabs" is still necessary and helpful for switching > languages. > > Best, > Jark > > [1]: > > https://nightlies.apache.org/flink/flink-docs-master/docs/dev/python/datastream/operators/windows/ > [2]: > > https://nightlies.apache.org/flink/flink-docs-master/docs/dev/datastream/operators/windows/ > > > > > > > > On Tue, 22 Mar 2022 at 21:40, Konstantin Knauf <kna...@apache.org> wrote: > > > Hi everyone, > > > > I would like to discuss a particular aspect of our documentation: the > > top-level structure with respect to languages and APIs. The current > > structure is inconsistent and the direction is unclear to me, which makes > > it hard for me to contribute gradual improvements. > > > > Currently, the Python documentation has its own independent branch in the > > documentation [1]. In the rest of the documentation, Python is sometimes > > included like in this Table API page [2] and sometimes ignored like on > the > > project setup pages [3]. Scala and Java on the other hand are always > > documented in parallel next to each other in tabs. > > > > The way I see it, most parts (application development, connectors, > getting > > started, project setup) of our documentation have two primary dimensions: > > API (DataStream, Table API), Language (Python, Java, Scala) > > > > In addition, there is SQL, for which the language is only a minor factor > > (UDFs), but which generally requires a different structure (different > > audience, different tools). On the other hand, SQL and Table API have > some > > conceptual overlap, whereas I doubt these concepts are of big interest > > to SQL users. So, to me SQL should be treated separately in any case with > > links to the Table API documentation for some concepts. > > > > I think, in general, both approaches can work: > > > > > > *Option 1: "Language Tabs"* > > Application Development > > > DataStream API (Java, Scala, Python) > > > Table API (Java, Scala, Python) > > > SQL > > > > > > *Option 2: "Language First" * > > Java Development Guide > > > Getting Started > > > DataStream API > > > Table API > > Python Development Guide > > > Getting Started > > > Datastream API > > > Table API > > SQL Development Guide > > > > I don't have a strong opinion on this, but tend towards "Language First". > > > > * First, I assume, users actually first decide on their language/tools of > > choice and then move on to the API. > > > > * Second, most of the Flink Documentation currently is using a "Language > > Tabs" approach, but this might become obsolete in the long-term anyway as > > we move more and more in a Scala-free direction. > > > > For the connectors, I think, there is a good argument for "Language & API > > Embedded", because documenting every connector for each API and language > > separately would result in a lot of duplication. Here, I would go one > step > > further then what we have right now and target > > > > Connectors > > -> Kafka (All APIs incl. SQL, All Languages) > > -> Kinesis (same) > > -> ... > > > > This also results in a quick overview for users about which connectors > > exist and plays well with our plan of externalizing connectors. > > > > For completeness & scope of the discussion: there are two outdated FLIPs > on > > documentation (42, 60), which both have not been implemented, are > partially > > contradicting each other and are generally out-of-date. I specifically > > don't intend to add another FLIP to this graveyard, but still reach a > > consensus on the high-level direction. > > > > What do you think? > > > > Cheers, > > > > Konstantin > > > > -- > > > > Konstantin Knauf > > > > https://twitter.com/snntrable > > > > https://github.com/knaufk > > > -- Konstantin Knauf | Head of Product +49 160 91394525 Follow us @VervericaData Ververica <https://www.ververica.com/> -- Join Flink Forward <https://flink-forward.org/> - The Apache Flink Conference Stream Processing | Event Driven | Real Time -- Ververica GmbH | Invalidenstrasse 115, 10115 Berlin, Germany -- Ververica GmbH Registered at Amtsgericht Charlottenburg: HRB 158244 B Managing Directors: Karl Anton Wehner, Holger Temme, Yip Park Tung Jason, Jinwei (Kevin) Zhang
