Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Matplotlib
- Redactor técnico:
- jeromev
- Nombre del proyecto:
- Cómo desarrollar rutas de entrada de Matplotlib
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Introducción
La sugerencia del proyecto de Matplotlib para la temporada de Documentos de Google de este año implica crear contenido que ayude a presentar Matplotlib a los usuarios nuevos. Para desarrollar rutas de entrada de Matplotlib, propongo un enfoque alternativo al de la documentación actual. Soy una escritora técnica nueva de la industria, pero mis antecedentes son campos relacionados con la educación y otros relacionados con la educación. La redacción técnica y la educación tienen fuertes paralelos que se enfocan en producir contenido que empatice y permita a los usuarios realizar sus tareas con los recursos proporcionados.
En este contexto, la documentación de Matplotlib se beneficiaría con una mejora para empatizar con los usuarios nuevos. Actualmente, gran parte del material consta de datos aleatorios y de imágenes no etiquetadas. Son excelentes para mostrar rápidamente las imágenes y las funciones de Matplotlib. Sin embargo, para el caso de uso de alguien nuevo en Matplotlib, es difícil atravesar la transformación de datos en elementos visuales.
Un contexto en un enfoque expuesto es una solución a este obstáculo. Al escribir un procedimiento desde la perspectiva de un ejemplo del mundo real, estamos demostrando una comprensión del entorno en el que trabaja un usuario. Esto mejora la relación que tienen la documentación y el usuario en términos de alcanzar un objetivo o una expectativa de completar una tarea.
Un usuario tiene un propósito derivado coherente. Por ejemplo, un científico de datos de una empresa de calzado debe presentar datos de clientes a un equipo para ilustrar las tendencias de compra a lo largo del tiempo. En esta situación, el usuario debe aprender a navegar por Matplotlib y aprovechar las herramientas dentro de la biblioteca para completar la tarea en cuestión.
Con contexto adicional para respaldar la documentación, un usuario nuevo puede identificarse más con el tema. El propósito derivado del usuario es paralelo al de la documentación. Espero trabajar en pos de la visión que el desarrollador principal Tom Caswell analizó en una entrevista en 2017 como “tener a alguien que realmente pueda escribir y tenga empatía con los usuarios, para revisar y básicamente escribir un libro “Introducción a Matplotlib” de 200 páginas, y que esa sea la entrada principal a los documentos”.
Enfoque alternativo de la escritura expuesta
La documentación actual demuestra las funciones de Matplotlib, es decir, lo que un usuario puede hacer con la biblioteca. Por ejemplo, un tutorial a menudo sigue el patrón que no implica una explicación del método subyacente.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
A menudo, con la documentación y asistencia de programación, se recomienda al usuario que ejecute el código por su cuenta para comprender lo que sucede. Aunque una mentalidad de programación mejora la comprensión del usuario sobre el tema, la curva de aprendizaje de las transformaciones tiene poco contenido de respaldo. Puede ser un desafío abrumador, ya que la documentación es limitada.
Proporcionar diagramas, imágenes u otros elementos visuales adicionales ayudará a crear nuevas oportunidades de aprendizaje. La siguiente estructura también sirve como una plantilla para el contenido nuevo. Además, agregar imágenes o gráficos no textuales podría beneficiarse con funciones como textos destacados y marcas de verificación. Hay momentos en los que es más difícil navegar por las imágenes sin indicaciones de cómo o dónde el código se transforma en el resultado ejecutado. Creo que falta un elemento visual fuerte que podría fomentar una mayor comprensión de los temas.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
El enfoque alternativo de usar escritura expositiva para la documentación tiene un potencial enorme. Con los usuarios viendo una variedad de conceptos para las transformaciones, podrían identificar mejor las estrategias subyacentes para desarrollar visualizaciones de datos. Este conocimiento puede ayudar a los usuarios a innovar y aprovechar las funciones que se presentan en los ejemplos basados en casos de uso realistas.
A medida que Matplotlib se vuelve más popular, la coherencia en la facilidad de uso y la accesibilidad son testimonio de la reputación de la biblioteca. Estas características permiten demostrar patrones y estrategias comunes que pueden aparecer no solo en el código, sino también en la documentación. Si Matplotlib es sencillo y estándar para los usuarios, el programa, como se evidencia en su creciente uso y expansión de recursos, también puede ser así para la documentación técnica.
Cuando los usuarios tienen problemas, es común utilizar la búsqueda para resolverlos. En lugar de depender de la búsqueda como el método principal de navegación, puede tener más impacto que los usuarios creen su propio plan de estudios dentro de la documentación. En este sentido, un usuario busca una solución a su problema y, luego, cuando encuentra otro problema o necesita información adicional, utiliza vínculos incorporados y completos en todo momento.
Esto implicaría una arquitectura ascendente en el sistema organizacional. Para cada tema dentro de Matplotlib, una red rica de vínculos a afinidades de temas, así como temas informativos, ayudaría a construir una red sólida. A lo largo de esta red, es más probable que un usuario siga utilizando la documentación a medida que navega a su tema y explora cada vez más información relacionada con ese tema.
Obstáculos
Siempre hay desafíos con un proyecto tan completo y detallado como este. Como escritor técnico más nuevo en la industria, tengo poca experiencia en el uso de Sphinx y ReST para escribir documentación. También soy principiante cuando se trata de Matplotlib y Git. Lleva tiempo abordar estos cuatro sistemas y familiarizarse con ellos para la colaboración y la investigación. Tendré que delegar tiempo durante la fase de vinculación con la comunidad y antes para sentar las bases necesarias para las rutas de nivel inicial. Durante este período, si tengo problemas con los conceptos y los aspectos básicos, tendré que comunicarme con la comunidad para obtener más asistencia.
La coordinación de los esfuerzos de colaboración entre zonas horarias y plataformas en línea también requerirá algunos ajustes. Hay varias vías de comunicación que utilizan las personas de toda la industria, por lo que es una cuestión de asegurarme de que soy accesible y accesible en todos los medios. Seré transparente al priorizar las diferentes expectativas en todo momento. Aunque recién estoy empezando a aceptar trabajos como este en la industria, estoy comprometido con hacerme responsable y estar abierto a los comentarios y las críticas. Siento que estas cualidades son valiosas sin importar el campo.
Además, aumentar las pruebas de usabilidad es una sección de documentación que creo que beneficiaría las rutas de entrada de Matplotlib. Realizar encuestas de usabilidad sobre el contenido tiene el propósito de proporcionar el perfil de un usuario, es decir, las personas. La información como la experiencia del usuario, su sector y su historial de solución de problemas son valiosas. Estas piezas ayudan a formar el lenguaje detrás del procedimiento. Cuando la redacción se une a los lectores a su nivel, el contenido madura más allá de actuar como meramente instructivo.
Los grandes desafíos suelen implicar la creación de una práctica continua de pruebas de usabilidad. Es demasiado común haber tenido una única instancia de prueba, si se realizó, durante el desarrollo del contenido. Las pruebas de usabilidad frecuentes ayudan a impulsar la narrativa del contenido. Mi objetivo sería establecer un programa o realizar pruebas de usabilidad recurrentes con la comunidad de Matplotlib.
Conclusión
Tengo un poco de experiencia usando Python y Matplotlib en mi tiempo libre. La cantidad que aprendí por mi cuenta en los últimos meses fue gracias al apoyo de la documentación actual y a mi propia curiosidad. También tuve muchos videos y mentores en esa época. Todavía me queda mucho por aprender y todavía me quedan cosas por mejorar cuando armo mi propio plan de estudios de programación que me interesa.
Después de ver las ideas que Matplotlib y la comunidad tienen sobre GSoD, siento que sería una gran experiencia en crecimiento mejorar mis habilidades como escritor técnico y tener la oportunidad de aprender más de los expertos detrás de escena. Creo que este proyecto de Matplotlib es significativo y, a la vez, me apasiona en la ideología.
Mi objetivo como escritor técnico es ayudar a los usuarios a realizar las tareas que desean sin sentirse abrumados por las funciones disponibles para trabajar en una revisión de la guía de uso. Creo que la mejor documentación seguiría creciendo y adaptándose a los usuarios y permitiría que cada usuario navegue hacia sus propias soluciones.