Proyecto Bokeh

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:

Bokeh

Redactor técnico:

vis_verborum

Nombre del proyecto:

Creación, lectura y uso compartido: Cómo optimizar la documentación de Bokeh

Duración del proyecto:

Duración estándar (3 meses)

Project description

Creación, lectura y uso compartido: Optimiza la documentación de Bokeh

1. Resumen

Bokeh es una herramienta extremadamente eficaz para crear visualizaciones interactivas y basadas en el navegador con Python. Tiene una base de usuarios considerable (502,000 descargas mensuales de conda y 855,000 descargas de PyPi) y una gran cantidad de colaboradores (455 colaboradores en GitHub). No es de extrañar que la extensa documentación de Bokeh crezca de forma orgánica. Por lo tanto, en algunos lugares, es incoherente, difícil de acceder y complicada.

La Temporada de documentos de Google ofrece una oportunidad única para revisar y actualizar de forma focalizada la estructura y el contenido de la documentación de Bokeh, y para asegurarse de que la documentación, las herramientas y los flujos de trabajo asociados sean a prueba de futuro.

Codifiqué y documenté proyectos de código abierto con Python y Sphinx (los más recientes: PyZillow y PyPresseportal). Pero lo que me convierte en una participante única de la temporada de Documentos de Google es mi formación en periodismo: trabajé en salas de prensa por más de 13 años, durante muchos años como editor gerente y defensor del cambio digital. Además de mis tareas periodísticas, tuve cada vez más responsabilidades en el diseño y la documentación de nuevas herramientas digitales y guías de estilo, así como en la capacitación del personal de la redacción.

Después de mudarme recientemente de Europa a EE.UU., decidí explorar nuevas formas de combinar mi entusiasmo por la comunicación y la programación. La escritura técnica es la combinación óptima de mis habilidades y experiencias en escritura y tecnología. En esta propuesta, explicaré cómo usaré la Temporada de documentos de Google para optimizar la documentación de Bokeh: haciendo que la creación y la contribución a la documentación sean más convenientes, que la lectura de la documentación sea más sencilla y que sea más fácil compartir la información de la documentación con otras personas.

2. Situación actual

La documentación oficial de Bokeh consta de las siguientes unidades principales:

• Documentación narrativa: Guía de instalación, guía del usuario, guía para desarrolladores, notas de la versión
• Galería y demostraciones (ejemplos interactivos con su código fuente)
• Guía de referencia (documentación basada en docstrings)
• Instructivo (amplia colección de notebooks de Jupyter, alojada en mybinder.org)
• Cadenas de documentos y ayuda de modelos para IDEs
• Ejemplos y archivos readme en el repositorio del proyecto

Además, hay una gran cantidad de información disponible en el foro de asistencia de Bokeh y en Stack Overflow, donde el desarrollador de Bokeh responde de forma activa las preguntas de los usuarios, así como en el blog de Bokeh en Medium.

La mayoría de las páginas web de la documentación se crean con Sphinx, con varias extensiones estándar y personalizadas. La Guía de referencia, por ejemplo, se genera a partir de docstrings con extensiones como "autodoc" y "bokeh_autodoc" personalizadas. Como es la naturaleza de la documentación que se desarrolla de forma orgánica, contiene redundancias y contradicciones.

Una de las primeras cosas que noté cuando analicé la documentación existente fue la falta de lineamientos de estilo claros para la redacción de la documentación. La Guía para desarrolladores de Bokeh contiene algunas instrucciones básicas. Sin embargo, este documento no contiene mucha orientación sobre el estilo, en especial con respecto a la documentación que va más allá de las docstrings. Como consecuencia, los problemas estilísticos y estructurales dificultan el acceso a la información de los documentos, especialmente para los recién llegados.

Por ejemplo:

• El uso de sustantivos, gerundios y palabras poco comunes en lugar de verbos claros y contundentes hace que parte del texto sea innecesariamente complicado: “La observación principal es que el uso típico implica crear objetos de trama con la función figure()”. Se debe reformular para facilitar la lectura. Por ejemplo: “La función Figma() es la función más usada para crear objetos de diagramas”.
• Algunas oraciones son muy largas, por lo que son difíciles de comprender: "Luego, podemos llamar a vbar con la lista de factores de nombres de frutas como la coordenada x, la altura de la barra como la coordenada superior y, opcionalmente, cualquier ancho o cualquier otra propiedad que queramos establecer". Las oraciones más largas deben dividirse en oraciones más cortas o listas con viñetas. La simplificación de las oraciones será especialmente útil para los usuarios con dislexia o para las personas que no hablan inglés como idioma materno (consulta el problema #10160).
• Uso inconsistente de “tú” y “nosotros”, lo que genera confusión y distracción: “Existen dos métodos básicos que se pueden usar, según tu caso de uso” y “Podemos graficar todas las series de años con llamadas separadas” (dos ejemplos de la misma página). Algunas páginas se dirigen a los lectores de diferentes maneras, como “es posible que los usuarios deban instalar dependencias adicionales” o “se pueden crear diseños más complejos”.
• Los errores tipográficos, las palabras faltantes y superfluas, y los errores gramaticales interrumpen el flujo de lectura y dañan la credibilidad de la información: “Bokeh facilita la creación de gráficos de barras básicos” o “Consulta la sección de glifos de la Guía del usuario”.
• Las inconsistencias estructurales pueden ser frustrantes para los lectores, como tener ejemplos bien anotados en una página y no tener explicaciones de los ejemplos en otra página.

La página de destino de la documentación de Bokeh es bastante breve y no incluye información sobre todos los recursos disponibles (no se menciona la extensa biblioteca de docstrings y funciones de ayuda de modelos, los foros de asistencia, las demostraciones ni el blog de Medium). Esto también dificulta que los usuarios nuevos comiencen a usar Bokeh.

3. Objetivos

Para aprovechar la fase de desarrollo de documentos de once semanas de manera más eficiente, me enfocaré en tres elementos clave:

3.1. Mejora la creación de documentos

La mayor parte de la documentación de Bokeh está escrita por colaboradores que incluyen documentación como parte de solicitudes de extracción para nuevas funciones y correcciones de errores. Si bien usaré parte de la fase de desarrollo de la documentación para editar y refactorizar los documentos existentes, me enfocaré en hacer que los flujos de trabajo para crear y mantener la documentación sean a prueba de futuro: Debe ser lo más fácil posible para los colaboradores mantener un estándar de documentación alto y coherente.

Me aseguraré de lograrlo con dos enfoques:

• Crearé un conjunto de lineamientos de estilo prácticos y simples para incluir en la Guía para desarrolladores existente. En estos lineamientos, se abordarán el estilo, la gramática y la estructura. Además, usaré canales de comunicación interna, como Slack, para asegurarme de que los colaboradores de Bokeh conozcan los lineamientos de estilo. También ofreceré capacitación individual y sesiones de preguntas y respuestas para el equipo.
• Trabajaré con el equipo principal para encontrar un conjunto óptimo de herramientas para el control de calidad de la documentación, que se agregará a los flujos de trabajo existentes de Bokeh para las solicitudes de extracción (PR) y la integración continua (CI). Según los requisitos del equipo, esto podría implicar agregar herramientas como pydocstyle, proselint o la corrección ortográfica de sphinxcontrib-speling al paquete de pruebas de Bokeh, configuración de confirmación previa o acciones de GitHub. Agregué una prueba de concepto funcional a las acciones de GitHub de uno de mis propios proyectos de código abierto.

3.2. Mejora la lectura de los documentos

El objetivo de una buena documentación es facilitar que los usuarios actuales y potenciales encuentren exactamente la información correcta y puedan usarla de la manera más eficiente posible.

Los factores clave para la usabilidad de un texto son su estilo y estructura: escribir la documentación en un estilo claro y coherente permite que los lectores recojan la información rápidamente, sin distracciones ni lenguaje superfluo. Una estructura clara y transparente de la documentación facilita la búsqueda rápida de información relevante.

Me enfocaré en ambas áreas, con énfasis en la usabilidad para los usuarios nuevos. Esto incluirá una revisión exhaustiva de la documentación narrativa, centrada en la Guía del usuario. También revisaré la página de destino de la documentación para abordar con mayor claridad los diferentes públicos objetivo y asegurarme de que todos los usuarios puedan encontrar los recursos adecuados con rapidez.

Al igual que con la mejora de la creación de documentos que se describió anteriormente, me enfocaré en sentar las bases para futuras mejoras y estándares de alta calidad continuos para la documentación de Bokeh.

3.3. Mejora el uso compartido de los documentos

Cada vez hay más debates sobre Bokeh en plataformas de terceros. Muchas de estas plataformas usan metadatos, como OpenGraph de Facebook, para incluir vistas previas enriquecidas de los vínculos. Servicios como Facebook, Twitter, LinkedIn, Slack y iMessage usan OpenGraph. El foro Discourse de Bokeh también usa OpenGraph para renderizar vistas previas de vínculos.

Para usar esta tecnología, agregaré metadatos a las páginas web generadas por Sphinx de Bokeh, como se describe en el problema #9792. La forma más eficiente sería usar una extensión dedicada de Sphinx. Hace unos días, se publicó en GitHub una primera versión de una extensión de Sphinx para datos de OpenGraph. Usaré parte de la fase de desarrollo de la documentación para ayudar a mejorar esta extensión para usarla con la documentación de Bokeh.

También creé una prueba de concepto que estoy usando correctamente en uno de mis propios proyectos de código abierto, PyPresseportal. Esta extensión recopila automáticamente información relevante, como el título, la descripción, la imagen y la URL. Luego, inserta esta información en el código HTML generado por Sphinx como etiquetas OpenGraph.

El siguiente paso en el desarrollo de esta extensión sería implementar directivas personalizadas para definir manualmente los metadatos de OpenGraph (similares a las directivas "meta" existentes de docutil). Los metadatos generados automáticamente solo se usarían como resguardo, en caso de que no haya datos ingresados de forma manual disponibles.

La compatibilidad con los datos estructurados es mucho más compleja, por lo que me centraré principalmente en incluir metadatos de OpenGraph de alta calidad para la documentación de Bokeh. Todo el trabajo que se realice para admitir OpenGraph, al mismo tiempo, sentará las bases para la compatibilidad con los datos estructurados.

Los miembros de las comunidades de Sphinx y ReadTheDocs expresaron interés en desarrollar extensiones para OpenGraph y datos estructurados (en los problemas #1758 y #5208, por ejemplo), y me aseguraré de trabajar con ellos de forma estrecha.

4. Resultados

En resumen, estos son los resultados que espero obtener de la temporada de Documentos:

• Lineamientos de estilo de la documentación para los colaboradores de Bokeh
• Se revisaron los flujos de trabajo de PR y CI para incluir el control de calidad de la documentación automatizado
• Guía del usuario editada y reestructurada
• Página de destino de la documentación revisada
• Metadatos de OpenGraph incluidos en las páginas web de la documentación y una extensión de Sphinx que funcione

Además, mantendré un "doclog" para documentar mi recorrido a través de la temporada de Documentos de Google en mi sitio web personal/Medium o el blog de Medium de Bokeh. Esto también servirá como base para el informe del proyecto de Google. Haré todo el trabajo de forma transparente, en forma de problemas y solicitudes de extracción de GitHub, siempre que sea posible.

5. Cronograma

Antes de la fase de unión de la comunidad: Ya participé activamente en varios debates sobre el repositorio de GitHub de Bokeh y estuve en contacto con Bryan Van de Ven y Pavithra Eswaramoorthy, mentoras de Bokeh para la temporada de documentos de Google. Me mantendré activo en la conversación sobre Bokeh y también me familiarizaré más con Bokeh compilando y publicando visualizaciones.

Fase de vinculación con la comunidad (del 17/8 al 13/9):

• Conocer al equipo principal y definir mejor el plan del proyecto con los mentores
• Establece un programa y canales de comunicación para los informes y comentarios periódicos con los mentores.
• Estar activo en el canal de Slack de Bokeh para informar a todos los colaboradores interesados sobre la Temporada de Documentos de Google y los objetivos de la fase de desarrollo de documentos
• Recopilar comentarios de los colaboradores de Bokeh para definir mejor el plan de la fase de desarrollo de documentos

Fase de desarrollo de documentos

Semana 1, del 14 al 20 de septiembre:

• Comienza a auditar y editar la documentación narrativa.
• Empezar a esbozar las pautas de estilo

Semana 2, del 21 al 27 de septiembre:

• Continúa trabajando en los lineamientos de estilo
• Seguir editando la documentación narrativa
• Comienza a revisar la página de destino de la documentación

Semana 3, del 28 de septiembre al 4 de octubre:

• Finaliza los lineamientos de estilo
• Finaliza la página de destino de la documentación

Semana 4, del 5 al 11 de octubre:

• Finaliza la edición de la documentación narrativa
• Hablar con el equipo principal de Bokeh sobre la integración de herramientas para el control de calidad de documentos en los flujos de trabajo de PR/CI

Semana 5, del 12 al 18 de octubre:

• Organice una sesión de preguntas y respuestas con colaboradores de Bokeh en Slack para debatir sobre los lineamientos de estilo, las mejoras en la documentación narrativa y los flujos de trabajo de RR.PP./CI
• Comenzar a desarrollar mi prueba de concepto existente para los metadatos de OpenGraph en una extensión de Sphinx implementable
• Revisar los lineamientos de estilo en función de los comentarios de la sesión de preguntas y respuestas con los colaboradores de Bokeh

Semana 6, del 19/10 al 25/10:

• Comenzar a probar las herramientas para el control de calidad de los documentos en los flujos de trabajo de RR.PP. e CI
• Continuar con el desarrollo de la extensión de Sphinx para metadatos

Semana 7, del 26/10 al 1/11:

• Prueba de la extensión de Sphinx
• Segunda sesión de preguntas y respuestas con colaboradores de Bokeh en Slack
• Revisa las entregas en función de los comentarios de la segunda sesión de preguntas y respuestas

Semana del 8, del 2 al 8 de noviembre:

• Implementa la extensión de Sphinx y publica una página de destino y una documentación narrativa mejoradas

Semana 9, del 9 al 15 de noviembre:

• Implementa herramientas de control de calidad de documentos en los flujos de trabajo de relaciones públicas y CI
• Se actualizó y publicó la Guía para desarrolladores para incluir lineamientos de estilo y agregar flujos de trabajo de CI y RP

Semana 10, del 16 al 22 de noviembre:

• Finalizar las tareas restantes

Semana 11, del 23 al 29 de noviembre:

• Comienza a escribir el informe del proyecto
• Comienza a escribir la evaluación del proyecto

Fase de finalización del proyecto

Semana 12, del 30/11 al 5/12:

• Finalizar y enviar el informe del proyecto

Semana 13, del 03 al 10 de diciembre:

• Finaliza y envía la evaluación del proyecto

Después de que finalice la Temporada de Documentos de Google, ocurrirá lo siguiente:

• Espero estar involucrado en el desarrollo de Bokeh y seguir trabajando en su documentación.
• Planeo seguir desarrollando la extensión de Sphinx para los metadatos de OpenGraph/datos estructurados.
• Espero usar mis antecedentes en el periodismo y mi red existente para promocionar Bokeh como una herramienta en el periodismo de datos. Por ejemplo, escribiendo sobre Bokeh con un público periodístico en mente o ofreciendo charlas en conferencias sobre el uso de Bokeh en entornos periodísticos.

6. Acerca de mí

Originalmente, soy periodista y tengo experiencia en noticias de TV, en línea y radio. Trabajar como editor en jefe y reportero de noticias digitales y de TV me ha dado años de experiencia en redacción y edición. Al mismo tiempo, trabajé en varios proyectos que promovían la transformación digital y la automatización. Escribí varios manuales sobre herramientas y flujos de trabajo digitales, así como guías de estilo y estrategias de comunicación para marcas de noticias digitales. También entrené a los miembros del equipo para que usaran esas herramientas.

Siempre me han atraído las intersecciones entre la comunicación y la tecnología. Cuando aprendí a programar en Python, se me abrió un mundo completamente nuevo: por ejemplo, pude hacer análisis y visualización de datos para el periodismo de datos. Aprender a programar también me permitió trabajar activamente con ingenieros de software para desarrollar herramientas digitales para los flujos de trabajo de las salas de prensa.

Lamentablemente, los manuales y documentos que escribí en mi trabajo anterior no son públicos. Por lo tanto, ahora me estoy enfocando en participar más en proyectos de código abierto (consulta los ejemplos a continuación). Basé mi trabajo de redacción técnica en guías de estilo, como la guía de estilo de documentación para desarrolladores de Google y la guía de estilo de Microsoft. Uso GitHub, Slack y Linux con frecuencia. He escrito documentación narrativa, así como docstrings y sugerencias de tipo, con herramientas como Sphinx, Mypy y Sphinx autodoc.

Actualmente trabajo como autónomo. Mi agenda proporciona la flexibilidad necesaria para trabajar en la documentación de Bokeh durante alrededor de 25 horas a la semana durante la fase de desarrollo de la documentación. Trabajo en la zona horaria del Pacífico, pero me complace adaptarme a los horarios y las necesidades del equipo.

7. Ejemplos recientes de documentación de código abierto

• PyZillow: PyZillow es un wrapper de Python para la API del sitio web de bienes raíces Zillow.com. Además de proporcionar código y actuar como uno de los encargados de su mantenimiento, escribí la documentación completa. Usé Sphinx para la documentación narrativa y para la referencia del módulo. Creé la referencia del módulo con la extensión Autodoc de Sphinx, basada en las docstrings que agregué al código.

• PyPresseportal: PyPresseportal es un wrapper de Python para la API del sitio web presseportal.de. El sitio web presseportal.de es uno de los mayores distribuidores de comunicados de prensa y anuncios sobre relaciones con inversores en Alemania. Por ejemplo, casi todos los departamentos de policía y bomberos usan este servicio para distribuir sus comunicados de prensa. Después de usar la API durante muchos años como periodista, decidí desarrollar una interfaz de Python para acceder a los extensos recursos de datos del sitio web como objetos de Python. Escribí el código y toda la documentación basada en Sphinx.