Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Apache Flink
- Redactor técnico:
- haseeb1431
- Nombre del proyecto:
- Extensión de la API de Table y documentación de SQL para Apache Flink
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Envío mi solicitud para la GSOD sobre “Extender la API de Table y la documentación de SQL”. Escribiremos documentación de la API para que la abuela también pueda escribir consultas. Aunque ya podríamos tener la estructura, la analizaremos como usuarios principiantes y sugeriremos ideas cuando sea necesario. Planeo trabajar estrechamente con mentores para comprender su proceso de pensamiento y, al mismo tiempo, compartir diferentes ideas basadas en mi experiencia previa en la industria.
Estas son algunas de las ideas iniciales basadas en la documentación actual:
Actualmente, la página Resumen ofrece mucha información, pero se debe revisar y ordenar de forma tal que los usuarios principiante y avanzado puedan comenzar rápidamente. Mi idea es comenzar con diferentes pistas posibles, a) iniciar un nuevo proyecto y, luego, ejecutar las consultas sobre este, b) ejecutar consultas a la API de SQL o de tabla sobre un proyecto existente.
También debemos tener un mapa completo de la documentación de la API en la página de destino para que los usuarios puedan ver todas las posibilidades a primera vista. Será una versión mejorada de la sección "Qué hacer a continuación" de la página de descripción general actual.
La página de conceptos tiene un contenido bastante bueno, pero está demasiado cargado en una sola página, por lo que tendremos pocas sub secciones en esta página. Del mismo modo, otras secciones: Planificadores, Funciones integradas y Conectores necesitan más visibilidad, tal vez en la página de resumen o en la barra de navegación del lado izquierdo. La página Conectores se puede dividir en más secciones secundarias, p.ej., conectores, formatos, etcétera. Las funciones del sistema (integradas) me parecen adecuadas, ya que tenemos todos los métodos posibles disponibles en una sola página y los usuarios pueden consultarlas como guías de referencia en todo momento, pero con gusto agregaré más contenido sobre este tema.
El período de tres meses se dividirá en diferentes fases. Inicialmente, crearemos una estructura, como un mapa del sitio, para la documentación de la API de Table &SQL. Presentaremos las secciones secundarias y las historias como se compartió anteriormente. Una vez que esté completo, podremos revisarlo con usuarios avanzados y principiantes. Por otro lado, podemos empezar a escribir sobre los planificadores y conectores mientras esperamos los comentarios. Una vez que recibamos los comentarios, reestructuraremos nuestros documentos de la API. A continuación, nos enfocaremos en terminar de redactar las secciones pendientes. Por último, si el tiempo lo permite, planeo tomar un ejemplo desde cero y mostrar la implementación de un proyecto de extremo a extremo que se puede aprovechar para FLINK-12639.
Propongo que podamos tener una reunión de una hora después de 2 semanas, además de los chats en Slack (o cualquier otra herramienta). Compartiré un cronograma inicial del proyecto con las semanas previstas, lo que también nos ayudará a hacer un seguimiento del progreso del proyecto de forma semanal.
Por último, esta documentación es similar a nuestro blog en medium.com, en el que agregamos todos los detalles básicos cuando aprendemos diferentes funcionalidades de la API de Flink. También me convierte en un candidato único, ya que verificaré la documentación con implementaciones prácticas en lugar de solo escribir la documentación técnica. Este proyecto será un arma de doble filo para mí, ya que contribuiré a la documentación de código abierto mientras aprendo a usar la API de Table y SQL.