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:
- Matplotlib
- Escritor técnico:
- Jéromev
- 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 los usuarios nuevos. Para el desarrollo de rutas de entrada de Matplotlib, propongo un enfoque alternativo al de la documentación actual. Soy un nuevo escritor técnico de la industria, pero mis antecedentes son en campos relacionados con la educación y otros relacionados con ella. La redacción técnica y la educación tienen sólidos 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 la mejora de la empatía con los usuarios nuevos. Gran parte del material actual consta de datos aleatorios y de imágenes 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 nuevo en Matplotlib, es un desafío atravesar la transformación de datos a elementos visuales.
Un contexto en un enfoque explicativo 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 en una empresa de calzado debe presentar datos del cliente a un equipo para ilustrar las tendencias de compra a lo largo del tiempo. En esta situación, el usuario debe aprender a navegar 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 más con el tema. El propósito derivado del usuario es paralelo al de la documentación. Espero poder trabajar en pos de la visión que el desarrollador principal Tom Caswell analizó en una entrevista de 2017 como “tener a alguien que realmente pueda escribir y tenga empatía por 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 expositiva
En la documentación actual, se demuestran las funciones de Matplotlib, es decir, las acciones que un usuario puede hacer con la biblioteca. Por ejemplo, un instructivo 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 de programación y asistencia, se recomienda a un usuario ejecutar el código por su cuenta para comprender lo que sucede. Aunque una mentalidad de programación mejora la comprensión del usuario del 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 servirá como plantilla para el contenido nuevo. Además, el objetivo de agregar imágenes o gráficos no textuales podría beneficiarse de funciones como el texto destacado y las marcas de referencia. Hay momentos en los que 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 fuerte elemento visual 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}
Existe un potencial enorme en este enfoque alternativo de usar escritura expositiva para la documentación. Con los usuarios que vieran una variedad de conceptos para las transformaciones, podrían identificar mejor las estrategias subyacentes de 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 crece en popularidad, 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 que los usuarios lo programen, como se evidencia en el creciente uso y la expansión de los recursos, también puede ser así para la documentación técnica.
Cuando los usuarios se encuentran con problemas, es común usar 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, luego, cuando encuentra otro problema o desea información adicional, utilizará vínculos incrustados y completos en todo momento.
Esto implicaría una arquitectura ascendente en el sistema de la organización. 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 usando la documentación a medida que navega a su tema y explora más y más información relacionada con ese tema.
Obstáculos
Siempre hay desafíos con un proyecto tan integral y detallado como este. Como escritor técnico nuevo en la industria, tengo poca experiencia con Sphinx y ReST para escribir documentación. También soy principiante cuando se trata de Matplotlib y Git. Tomará tiempo abordar estos cuatro sistemas y familiarizarse con su uso para la colaboración y la investigación. Tendré que delegarle tiempo durante la fase de vinculación con la comunidad y antes a fin de 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á cierto ajuste. Hay varias vías de comunicación que utilizan las personas de toda la industria, por lo que es una cuestión de garantizar que soy accesible y accesible en todos los medios. Seré transparente cuando dé prioridad a las diferentes expectativas. A pesar de que recién estoy empezando a trabajar en 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 en cualquier campo.
Además, el aumento de las pruebas de usabilidad es una sección de documentación que creo que beneficiaría las rutas de entrada de Matplotlib. Realizar encuestas para mejorar la facilidad de uso del contenido tiene el propósito de proporcionar un perfil del usuario, es decir, las personas. La información como la experiencia del usuario, su sector y el historial de solución de problemas son valiosas. Estas piezas ayudan a formar el lenguaje detrás del procedimiento. Cuando la redacción llega a los lectores en su nivel, el contenido madura más allá de actuar como meramente instructivo.
Los grandes problemas suelen relacionarse con la creación de una práctica continua de pruebas de usabilidad. Es muy común haber tenido una sola instancia de prueba, si se hubiera realizado, durante el desarrollo del contenido. Las pruebas de usabilidad frecuentes ayudan a impulsar la narrativa del contenido. Mi objetivo sería establecer un cronograma o realizar pruebas de usabilidad recurrentes con la comunidad de Matplotlib.
Conclusión
Tengo un poco de experiencia en 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 varios videos y mentores en esa época. Todavía tengo mucho que aprender y mucho más por mejorar mientras armo 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, siento que sería una experiencia excelente en crecimiento para mejorar mis habilidades como escritor técnico y tener la oportunidad de aprender más de las personas detrás de escena. Creo que este proyecto de Matplotlib es significativo y que me apasiona en la ideología.
Cuando trabajo en la revisión de la guía de uso, mi objetivo como escritor técnico es ayudar a los usuarios a realizar las tareas que deseen sin verse abrumados por las funciones disponibles. Creo que la mejor documentación seguirá creciendo y adaptándose a los usuarios, y permitiría que cualquier usuario navegue a sus propias soluciones.