Proyecto Bokeh

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:
Bokeh
Escritor técnico:
vis_verborum
Nombre del proyecto:
Creación, lectura y uso compartido: optimización de la documentación de Bokeh
Duración del proyecto:
Duración estándar (3 meses)

Project description

Crear, leer y compartir: optimización de la documentación de Bokeh

1. Se puede abstraer

Bokeh es una herramienta extremadamente potente para crear visualizaciones interactivas, basadas en el navegador con Python. Tiene una base de usuarios considerable (502,000 descargas mensuales de conda, 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 se cultiva de forma orgánica. Por lo tanto, en algunos casos, es inconsistente, difícil de acceder y se vuelve complicada.

La temporada de documentos de Google ofrece una oportunidad única para revisar y revisar específicamente la estructura y el contenido de la documentación de Bokeh, y asegurarse de que la documentación y las herramientas y los flujos de trabajo asociados sean aptos para el futuro.

Codifiqué y documenté proyectos de código abierto con Python y Sphinx (más recientemente: PyZillow y PyPresseportal). Pero lo que me convierte en un participante único de la temporada de Documentos de Google es mi experiencia en periodismo: trabajé en salas de prensa durante más de 13 años, con muchos años como editor general y defensor del cambio digital. Además de mis responsabilidades periodísticas, tenía 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 las salas de prensa.

Después de un reciente mudanza de Europa a EE.UU., decidí explorar nuevas formas de unir mi entusiasmo por la comunicación y la programación. Creo que la escritura técnica es la combinación óptima de mis habilidades y experiencias de redacción y tecnología. En esta propuesta, explicaré cómo usaré la temporada de documentos de Google para optimizar la documentación de Bokeh: crear y contribuir a la documentación con mayor comodidad, leer la documentación de forma más sencilla y compartir información en la documentación con otras personas de forma más fácil.

2. Situación actual

La documentación oficial de Bokeh consta de estas 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)
  • DocString y ayuda de modelos para IDE
  • 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 activamente a las preguntas de los usuarios, y también en el blog Medium de Bokeh.

La mayoría de las páginas web de documentación se crean con Sphinx, y varias extensiones de Sphinx estándares y personalizadas. La Guía de referencia, por ejemplo, se genera a partir de docstrings, con extensiones como “autodoc” y el personalizado “bokeh_autodoc”. Como es la naturaleza de la documentación cultivada de forma orgánica, contiene inconsistencias y redundancias.

Una de las primeras cosas que noté al analizar la documentación existente fue la falta de pautas de estilo claras para la redacción de documentos. 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 docstrings. Como consecuencia, los problemas estilísticos y estructurales dificultan el acceso a la información de los documentos, especialmente para los principiantes.

Por ejemplo:

La página de destino de la documentación de Bokeh es bastante corta y no incluye información sobre todos los recursos disponibles (no se menciona la extensa biblioteca de docstrings y funciones de ayuda para 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 utilizar la fase de desarrollo de documentos de once semanas de manera más eficiente, me centraré 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 las solicitudes de extracción para nuevas funcionalidades y correcciones de errores. Si bien usaré parte de la fase de desarrollo de documentos para editar y refactorizar los documentos existentes, destacaré que los flujos de trabajo para crear y mantener la documentación están preparados para el futuro: debe ser lo más fácil posible para los colaboradores mantener un estándar de documentación sistemáticamente alto.

Me aseguraré de hacerlo mediante dos enfoques:

  • Crearé un conjunto de lineamientos de estilo prácticos y simples que se incluirán en la Guía para desarrolladores existente. Estos lineamientos abordarán el estilo, la gramática y la estructura. Además, usaré canales de comunicación internos, como Slack, para asegurarme de que los colaboradores de Bokeh conozcan los lineamientos de estilo. También ofreceré capacitaciones individuales y sesiones de preguntas y respuestas para el equipo.
  • Trabajaré con el equipo central a fin de 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 los RR.PP. (solicitudes de extracción) y la CI (integración continua). Según los requisitos del equipo, esto podría significar agregar herramientas como pydocstyle, proselint o la corrección ortográfica de sphinxcontribu-spelling al paquete de pruebas de Bokeh, la configuración previa a la confirmación o las acciones de GitHub. Agregué una prueba de concepto funcional a las acciones de GitHub de uno de mis proyectos de código abierto.

3.2. Mejorar la lectura de documentos

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

Los factores clave de la usabilidad de un texto son su estilo y estructura: escribir documentación con un estilo claro y coherente permite a los lectores recoger la información rápidamente, sin distracciones y lenguaje superfluo. Una estructura sencilla y transparente de la documentación facilita la búsqueda de información relevante con rapidez.

Me centraré en ambas áreas, con énfasis en la facilidad de uso para los usuarios nuevos. Esto incluirá una revisión exhaustiva de la documentación de la narrativa, centrada en la guía del usuario. También mejoraré la página de destino de la documentación para dirigirme a los diferentes públicos objetivo con mayor claridad y asegurarme de que cada usuario pueda encontrar los recursos adecuados rápidamente.

Al igual que mejorar la creación de documentos descritos anteriormente, me centraré en sentar las bases para mejoras futuras y estándares altos continuamente para la documentación de Bokeh.

3.3. Mejora el uso compartido de los documentos

Hay cada vez más debates sobre Bokeh en plataformas de terceros. Muchas de estas plataformas utilizan metadatos como OpenGraph de Facebook para incluir vistas previas enriquecidas de los vínculos. Algunos servicios usan OpenGraph, como Facebook, Twitter, LinkedIn, iMessage y Slack. 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 la Sphinx de Bokeh, como se describe en el error #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é algunas de las fases de desarrollo de documentos para mejorar esta extensión y usarla con la documentación de Bokeh.

También creé una prueba de concepto que uso con éxito en uno de mis 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 de OpenGraph.

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

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

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

4. Entregas

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

  • Lineamientos de estilo de la documentación para colaboradores de Bokeh
  • Flujos de trabajo de PR y CI revisados para incluir un control de calidad automatizado de la documentación
  • Guía del usuario editada y reestructurada
  • Página de destino de la documentación revisada
  • Los metadatos de OpenGraph incluidos en las páginas web de documentación y una extensión de Sphinx funcional

Además, guardaré un "doclog" para documentar mi recorrido por la temporada de Documentos de Google en mi sitio web personal/Medium o el blog de Bokeh Medium. Esto también servirá como base para el informe del proyecto para Google. Siempre que sea posible, trabajaré con transparencia, en forma de problemas de GitHub y solicitudes de extracción.

5. Cronograma

Antes de la fase de vinculación con la comunidad: Ya participo activamente en varios debates en el repositorio de GitHub de Bokeh y he estado en contacto con Bryan Van de Ven y Pavithra Eswaramoorthy, mentoras de Bokeh en la temporada de Documentos de Google. Me mantendré activo en la conversación sobre Bokeh y también me familiarizaré con Bokeh a través de la compilación y publicación de visualizaciones.

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

  • Conoce al equipo central, perfecciona el plan del proyecto a cambio de mentores
  • Configurar un cronograma y canales de comunicación para informar y enviar comentarios periódicamente a los mentores
  • Participa activamente en Slack de Bokeh para informar a todos los colaboradores interesados en 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 del documento

Fase de desarrollo del documento

Semana 1, del 14 al 20 de septiembre:

  • Comenzar a auditar y editar la documentación de la narrativa
  • Comenzar a redactar la pauta de estilo de las pautas de estilo

Semana 2, del 21 al 27 de septiembre:

  • Continuar trabajando en las pautas de estilo
  • Seguir editando la documentación de la narrativa
  • Comenzar a revisar la página de destino de la documentación

Semana 3, del 28 al 4 de octubre:

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

Semana 4, 05/10 al 11/10:

  • Finaliza la edición de la documentación narrativa
  • Debatir con el equipo principal de Bokeh sobre la integración de herramientas para el control de calidad de los documentos en los flujos de trabajo de relaciones públicas y CI

Semana 5, del 12 al 18 de octubre:

  • Organiza una sesión de preguntas y respuestas con colaboradores de Bokeh en Slack para conversar sobre los lineamientos de estilo, las mejoras en la documentación narrativa y los flujos de trabajo de relaciones públicas/CI
  • Comenzar a desarrollar mi prueba de concepto existente para metadatos de OpenGraph en una extensión de Sphinx implementable
  • Revisar los lineamientos de estilo en función de los comentarios de las sesiones de preguntas y respuestas con los colaboradores de Bokeh

Semana 6, del 19 al 25 de octubre:

  • Comenzar a probar herramientas para el control de calidad de documentos en flujos de trabajo de relaciones públicas y de CI
  • Continuar el desarrollo de la extensión de Sphinx para los metadatos

Semana 7, 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
  • Revisar los entregables en función de los comentarios de la segunda sesión de preguntas y respuestas

Semana 8, del 2 al 8 de noviembre:

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

Semana 9, del 9 al 15 de noviembre:

  • Implementar herramientas de control de calidad de documentos en los flujos de trabajo de relaciones públicas y IC
  • Actualizar y publicar la Guía para desarrolladores a fin de incluir pautas de estilo y adiciones al flujo de trabajo de relaciones públicas y IC

Semana 10, del 16 al 22 de noviembre:

  • Finaliza las tareas restantes

Semana 11, del 23/11 al 29/11:

  • Comenzar a redactar el informe del proyecto
  • Comenzar 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:

  • Finalizar y enviar la evaluación del proyecto

Después de concluir la temporada de Documentos de Google, sucederá lo siguiente:

  • Espero seguir participando en el desarrollo de Bokeh y seguir trabajando en su documentación.
  • Planeo continuar el desarrollo de una extensión de Sphinx para metadatos de OpenGraph y datos estructurados.
  • Espero usar mis antecedentes en periodismo y mi red actual para promocionar Bokeh como una herramienta de periodismo de datos. Por ejemplo, puedes escribir sobre el bokeh con un público periodístico en mente u ofrecer charlas sobre el uso del bokeh en contextos periodísticos.

6. Acerca de mí

Soy periodista y tengo experiencia en TV, noticias en línea y radiales. Trabajar como editora general y reportera en TV y noticias digitales me ha dado años de experiencia en redacción y edición. Al mismo tiempo, trabajé en varios proyectos para promover la transformación digital y la automatización. Escribí numerosos manuales sobre herramientas y flujos de trabajo digitales, así como guías de estilo y estrategias de comunicación para las marcas de noticias digitales. También capacité a los miembros del equipo en el uso de 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: pude hacer análisis y visualización de datos para el periodismo de datos, por ejemplo. Aprender a programar también me permitió trabajar activamente con ingenieros de software en el desarrollo de herramientas digitales para flujos de trabajo en 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 involucrarme más con los proyectos de código abierto (consulta los ejemplos a continuación). Mi trabajo de redacción técnica se basó en guías de estilo, como la guía de estilo de la documentación para desarrolladores de Google y la de Microsoft. Uso GitHub, Slack y Linux con regularidad. Estuve escribiendo documentación narrativa, así como docstrings y sugerencias de tipo, usando herramientas como Sphinx, Mypy y Sphinx Autodoc.

Actualmente trabajo como freelancer. Mi agenda ofrece la flexibilidad necesaria para trabajar en la documentación de Bokeh durante aproximadamente 25 horas semanales durante la fase de desarrollo del documento. Trabajo en la zona horaria del Pacífico, pero con gusto me comunicaré con 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 mantener el código, escribí la documentación completa. Usé Sphinx para la documentación de la narrativa, además de la referencia del módulo. Creé la referencia del módulo con el documento automático de la extensión de Sphinx, basado 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 utilizan 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.