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:
- 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 de proyecto de Matplotlib para la temporada de Documentos de Google de este año implica crear contenido que ayude a presentar Matplotlib a nuevos usuarios. Para desarrollar rutas de entrada de Matplotlib, propongo un enfoque alternativo al de la documentación actual. Soy un escritor técnico nuevo en la industria. Sin embargo, mi formación es en educación y campos afines. La escritura técnica y la educación tienen fuertes paralelismos 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 de mejoras para empatizar con los usuarios nuevos. Actualmente, gran parte del material consiste en datos aleatorios y elementos visuales sin etiquetar. Son excelentes para mostrar rápidamente las imágenes y las funciones de Matplotlib. Sin embargo, para el caso de uso de alguien que es nuevo en Matplotlib, es un desafío recorrer la transformación de datos en imágenes.
Un contexto en un enfoque expositivo es una solución a este obstáculo. Al escribir un procedimiento desde el punto de vista de un ejemplo del mundo real, estamos demostrando que se entiende el 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 en 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 de la biblioteca para completar la tarea en cuestión.
Con contexto adicional para respaldar la documentación, un usuario nuevo puede identificarse mejor con el tema. El propósito derivado del usuario es paralelo a la documentación. Espero trabajar en la visión que el desarrollador principal Tom Caswell describió en una entrevista en 2017 como “tener a alguien que realmente pueda escribir y tenga empatía por los usuarios, para que revise y escriba básicamente un libro de 200 páginas sobre la introducción a Matplotlib, y que esa sea la entrada principal a los documentos”.
Enfoque alternativo de escritura expositiva
La documentación actual demuestra las funciones de Matplotlib, es decir, lo que un usuario puede hacer con la biblioteca. Por ejemplo, un instructivo suele seguir 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 la asistencia de programación, se recomienda que el usuario 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 para las transformaciones tiene poco contenido de apoyo. Puede ser un desafío abrumador, ya que la documentación es limitada.
Proporcionar diagramas, imágenes o cualquier otro elemento visual adicional ayudará a crear nuevas oportunidades de aprendizaje. La siguiente estructura también serviría como plantilla para contenido nuevo. Además, el objetivo de agregar imágenes o gráficos no textuales podría beneficiarse de funciones como textos destacados y marcas de posición. En ocasiones, es más difícil navegar por las imágenes sin indicaciones de cómo o dónde se transforma el código en el resultado ejecutado. Creo que falta un elemento visual sólido que podría fomentar una mejor comprensión de los temas.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Este enfoque alternativo de usar la escritura expositiva para la documentación tiene un potencial enorme. Si los usuarios ven una variedad de conceptos para las transformaciones, podrán identificar mejor las estrategias subyacentes para desarrollar visualizaciones a partir de datos. Este conocimiento puede ayudar a los usuarios a innovar y aprovechar las funciones, como se presenta en ejemplos basados en casos de uso realistas.
A medida que Matplotlib gana popularidad, la coherencia en la facilidad de uso y la accesibilidad son testimonio de la reputación de la biblioteca. Estas características se prestan para demostrar patrones y estrategias comunes que pueden surgir no solo dentro del código, sino también dentro de la documentación. Si Matplotlib es sencillo y estándar para que los usuarios programen, como se evidencia en su uso creciente y en la expansión de los recursos, también puede ser así para la documentación técnica.
Cuando los usuarios encuentran problemas, es común que usen la búsqueda para resolverlos. En lugar de depender de la búsqueda como el método principal de navegación, puede ser más impactante hacer 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, cuando encuentra otro problema o desea obtener información adicional, utiliza los vínculos incorporados y detallados en todo momento.
Esto implicaría una arquitectura ascendente en el sistema organizativo. Para cada tema dentro de Matplotlib, una red rica de vínculos a afinidades de temas, así como a temas informativos, ayudaría a crear una red sólida. A lo largo de esta red, es más probable que un usuario siga usando la documentación a medida que navega a su tema y explora cada vez más información relacionada con él.
Obstáculos
Siempre hay desafíos con un proyecto tan completo y detallado como este. Como escritor técnico nuevo en la industria, tengo experiencia limitada en el uso de Sphinx y ReST para escribir documentación. También soy principiante en Matplotlib y Git. Dominar estos cuatro sistemas y acostumbrarse a usarlos para la colaboración y la investigación llevará tiempo. Tendré que delegar tiempo durante la fase de vinculación con la comunidad y antes para crear la base necesaria para las trayectorias de nivel inicial. Durante este tiempo, si tengo problemas con los conceptos y los aspectos básicos, tendré que comunicarme con la comunidad para obtener más ayuda.
La coordinación de esfuerzos colaborativos en diferentes zonas horarias y plataformas en línea también requerirá algunos ajustes. Hay una variedad de vías de comunicación que utilizan las personas de toda la industria, por lo que se trata de asegurarme de que sea accesible en todos los medios. Seré transparente al establecer el orden de prioridad de las diferentes expectativas en todo momento. Aunque recién estoy comenzando a aceptar trabajos como este en la industria, me comprometo a ser responsable y a estar abierto a los comentarios y las críticas. Creo que estas cualidades son valiosas en cualquier campo.
Además, aumentar las pruebas de usabilidad es una sección de la documentación que creo que beneficiaría a las instrucciones de entrada de Matplotlib. Realizar encuestas de usabilidad en relación con el contenido tiene como objetivo proporcionar un perfil de usuario, es decir, arquetipos. La información como la experiencia del usuario, su industria y el historial de solución de problemas es valiosa. Estos elementos ayudan a formar el lenguaje detrás del procedimiento. Cuando la escritura llega a los lectores en su propio nivel, el contenido madura más allá de actuar como únicamente educativo.
A menudo, las mayores dificultades se encuentran en la creación de una práctica continua de pruebas de usabilidad. Es muy común tener una sola instancia de prueba, si es que se realiza alguna, durante el desarrollo del contenido. Las pruebas de usabilidad frecuentes ayudan a impulsar la narrativa del contenido. Sería mi esperanza de configurar un cronograma o tener pruebas de usabilidad recurrentes con la comunidad de Matplotlib.
Conclusión
Tengo algo de experiencia en el uso de Python y Matplotlib en mi tiempo libre. La cantidad de información que aprendí por mi cuenta en los últimos meses fue con el apoyo de la documentación actual y mi propia curiosidad. También tuve algunos videos y mentores en ese momento. Aún tengo mucho que aprender y mucho más margen de mejora a medida que creo mi propio plan de estudios de programación que me interesa.
Después de ver las ideas que Matplotlib y la comunidad tienen para GSoD, creo que sería una excelente experiencia de crecimiento mejorar mis habilidades como escritor técnico y tener la oportunidad de aprender más de las personas que trabajan detrás de escena. Sentí que este proyecto de Matplotlib es significativo y algo que me apasiona en la ideología.
Para trabajar en una revisión de la guía de uso, mi objetivo como escritor técnico es ayudar a los usuarios a realizar las tareas que desean sin sentirse abrumados por las funciones disponibles. Creo que la mejor documentación seguiría creciendo y adaptándose a los usuarios, y permitiría que cualquier usuario navegue a sus propias soluciones.