This page contains the details of a technical writing project accepted for Season of Docs.
- Open source organization:
- Apache Flink
- Technical writer:
- Kartik Khare
- Project name:
- Extend the Table API & SQL Documentation
- Project length:
- Long running (5 months)
Flink SQL shows staggering promise. The idea that you can work on Streams using just SQL is obvious but complicated. I believe Flink SQL can ultimately remove the need for data engineers for trivial analysis on realtime data such as counting requests for Uber/Lyft in various cities in realtime. The first step towards this goal is to simplify the documentation such that someone with an analytics background can also get started.
Here are some of the improvements I am planning for the docs. We can discuss more of them when we actually get started with the documentation - * The overview page doesn't contain any examples. It should contain easy examples to provide an intro to Table API. * Concepts & Common API page should be split up. * The functions should have a separate page for each category. The functions should also be listed in a tabular fashion with name, input data, parameters (if any), and return value as columns. * Data Type page should contain proper mappings of JAVA data-type → SQL data-type. The current representation is in the form of paragraphs but ideally, it should be a table. * The expression Syntax section on Table API page should have better formatting. * A completely new page on Planners and how users can take advantage of them. * A page on optimizations that are right now scattered throughout multiple sections. SQL Overview page also needs to be reformatted.
The content also needs a rework as it feels a bit overwhelming. We also need to add a section on where you can use Table API instead of Streaming API with comparisons such as a decrease in lines of code, better implicit optimizations, better readability, and easier debugging.