Status

Current state"Under Discussion"

Discussion thread: https://lists.apache.org/thread.html/0480d17dad32c2df62b3d401385f2140e221b42ee696494a14f73dc5@%3Cdev.flink.apache.org%3E

JIRA:

Released: <Flink Version>

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast).

Motivation

The documentation for Table & SQL API has evolved over time. In the meantime, more streaming concepts, a SQL Client, connectors, catalogs etc. were added. Also the vision of a unified API for both batch and streaming is making progress.

It is time to rework the structure in order to:

Public Interfaces

Not applicable.

Proposed Changes

This structure aims to get to the point quickly. It shows the features early to attract users and uses cross links e.g. to execution or concepts for interested readers.

The top-level pages are:


Overview                      *we start with a good overview*                       

Table API                      *get to the point, the features and operations*

SQL                                *get to the point, the features and operations*

Setup & Execution    *explain the setup and how to execute features*

Connect to External Systems       *details*

Built-in Functions                             *details*

Configuration                                     *details*

User-defined Extensions               *custom details*

Concepts                                             *reference from other pages*

Detailed Structure


Compatibility, Deprecation, and Migration Plan

We redirect old page links to the new structure.

Test Plan

Not applicable.

Rejected Alternatives

The first version was more like a walkthrough to guide the reader:

Getting Started
Overview
Planners
Concepts

Executing Programs
Table API

SQL Client

Data Types                                 *we start with available data types*
Connect to External Systems *a program starts with connectors*
SQL                                              *continue with operators*
Built-in Functions                     *and functions*

Configuration                            *finally we tweak the execution*


However, the problem here was that a user would read a lot of "boring" concept pages first and the actual list of operations would be nested in the Table API section and SQL section. The API sections should have highest priority and be presented as one of the first items in the list.