This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Apache Flink
- Technical writer:
- haseeb1431
- Project name:
- Extension of Table API & SQL Documentation for Apache Flink
- Project length:
- Standard length (3 months)
Project description
I am submitting my application for the GSOD on “Extend the Table API & SQL Documentation”. We will write API documentation such that grandma can write queries as well. Although, we already might have the structure but we will go through it as novice users and suggest ideas wherever required. I am planning to work closely with mentors to understand their thought process while sharing different ideas based on my prior industry experience.
Some of the initial thoughts based on current documentation are:
Overview page is currently a lot of information but needs to be revisited and ordered in a way that a beginner and advanced user both can start quickly. My idea is to have a getting started with different possible tracks, a) starting a new project and then running the queries on top of it, b) running SQL or Table API queries on top of an existing project.
We also need to have a complete map of the API documentation on the landing page so users can see all the possibilities at first glance. It will be an improved version of the “Where to go next” section on the current overview page.
Concept page has quite good content but it’s too much crammed onto a single page so we will have few subsections on this page. Similarly, other sections Planners, Built-in functions, Connectors need more visibility maybe on the overview page or left-hand side navigation bar. Connectors page can be divided into more sub-sections e.g. connectors, formats, and so on. System (Built-in) functions look fine to me since we have all the possible methods available on a single page and users can refer to them as cheat sheets all the time but will be happy to add more content around that.
The three month period will be divided into different phases. Initially, we will create a structure, like a sitemap, of the Table & SQL API documentation. We will introduce sub-sections and introduce story lines as shared above. Once completed, then we can have it reviewed with advance and beginner level users. On the other hand, we can start writing about the planners, connectors while we are waiting for the feedback. Once we have received the feedback, we will restructure our API docs. Next, we will focus to finish the writing for pending sections. Finally, If time allowed, I am planning to take an example from scratch and show case end to end project implementation which can be leveraged for FLINK-12639.
I propose that we can have an hour meeting after 2 weeks other than chats on slack (or any other tools). I will share an initial project timeline with expected weeks which will help us track the project progress on a weekly basis as well.
Finally, this documentation is similar to our blog on medium.com where we are adding all the basic details when we are learning different functionalities of Flink API. It also makes me a unique candidate as I will be verifying the documentation with hands-on implementations rather than just writing the technical docs. This project will work as a dual sword for me as I will contribute to the open-source documentation while learning the Table and SQL API.