Proyecto SciPy

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:

SciPy

Redactor técnico:

mkg33

Nombre del proyecto:

Documentación orientada al usuario y reestructuración exhaustiva

Duración del proyecto:

Duración estándar (3 meses)

Project description

Motivación:

Mi intención es trabajar en la refactorización de la documentación existente para que los usuarios con diferentes necesidades puedan acceder a ella fácilmente. No hace falta decir que un investigador probablemente esté interesado en funciones avanzadas y sutiles, mientras que un usuario sin experiencia previa aprecia las guías y diagramas paso a paso.

Me interesa llevar a cabo este proyecto por motivos personales y profesionales: en primer lugar, me gustaría contribuir de manera significativa a SciPy porque mi propia investigación se ha beneficiado mucho de él y, en segundo lugar, encuentro documentación insuficiente (o faltante) con demasiada frecuencia en otros software y siempre me pregunto qué tan rápido (si es que lo hacen) los usuarios podrían aprender a usar el código si se les proporcionara una guía exhaustiva.

Objetivos:

Mi objetivo es mejorar la documentación existente de SciPy en términos de contenido y gráficos. La característica más importante de mi enfoque a este problema es la implementación y el análisis de la encuesta a los usuarios, es decir, una encuesta concisa realizada en línea que permite a varios usuarios expresar sus necesidades con respecto a la documentación. Creo firmemente que sus opiniones deben ser una fuente de inspiración (¿de qué otra manera podemos crear una documentación más fácil de usar?).

En lo que respecta a la realización del proyecto en sí, la primera fase implicará diseñar y analizar la encuesta para los usuarios, así como abordar varios problemas de estilo que noté en la documentación actual. Por ejemplo, falta de coherencia (por ejemplo, arrays de dos dimensiones que se producen junto con arrays de dos dimensiones), oraciones complicadas que deben reescribirse o falta de orden alfabético en ciertas subpáginas. La segunda fase se enfocará en la presentación de guías gráficas que contengan hipervínculos a los temas relevantes (según los resultados de la encuesta y otras solicitudes de la comunidad). A largo plazo, quiero lograr una documentación satisfactoria adaptada a diferentes tipos de usuarios. Además, intentaré que los instructivos sean más coherentes desde el punto de vista lingüístico y estructural. Por último, mi objetivo es escribir instructivos nuevos (en función de las necesidades actuales de la comunidad).

Encuesta a los usuarios:

Con respecto a la encuesta de usuarios, propongo que utilices Formularios de Google por varias razones. En primer lugar, Formularios de Google es gratuito y ofrece una funcionalidad ilimitada (en cuanto a la cantidad de encuestados, preguntas, etc.), tiene un formato visual atractivo, las opciones de encuesta más útiles (por ejemplo, la escala lineal personalizable, las casillas de verificación y la opción múltiple) y, lo que es más importante, los resultados se pueden exportar fácilmente para los fines de análisis estadístico. Según una investigación en línea, parece que Formularios de Google es, al menos por ahora, la mejor herramienta gratuita para realizar encuestas. En un tono menos serio, sería un buen gesto usar un producto de Google en una iniciativa dirigida por Google.

Creé una encuesta preliminar con preguntas de muestra (puedes acceder a ella en https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). En la versión final, la cantidad razonable de preguntas debe ser de entre diez y quince. Para obtener resultados concretos, sugiero que usemos principalmente preguntas de opción múltiple, una escala lineal y algunas casillas de verificación. Sin embargo, la escala lineal no debe parecerse a un espectro completo (solo causa confusión y es probable que los resultados tengan una alta dispersión). Debe haber como máximo dos preguntas abiertas; de lo contrario, los resultados serán muy dispersos y no resultarán útiles. Creo que incluso una cantidad muy alta de respuestas no sería un problema, ya que los datos se pueden exportar y analizar fácilmente de forma automática con software estadístico. Si la cantidad de respuestas es muy alta, el análisis de las preguntas abiertas podría llevar un poco de tiempo, pero no creo que sea abrumador. Después de todo, es poco probable que un usuario promedio escriba un ensayo sobre el estado de la documentación. En el peor de los casos, algunas respuestas se pueden almacenar para un análisis futuro.

Guías gráficas:

Mi visión de las guías gráficas (destinadas a que sirvan como herramientas de navegación) se basa en una premisa popular de que (la mayoría) los seres humanos son mejores para procesar estructuras visuales directas en lugar de información puramente basada en texto. Además, un diagrama orientado a temas con líneas que conectan temas de interés similares es, sin duda, un recurso muy valioso para los usuarios menos experimentados (y no solo para ellos).

En cuanto a los detalles de la implementación, propongo usar el paquete TikZ. En primer lugar, es una herramienta potente y no parece estar en riesgo de quedar obsoleta pronto. También ofrece un resultado de alta calidad, tiene una documentación muy sólida y es un tema frecuente en TeX StackExchange y otros foros populares. Lo más importante es que la integración de un archivo TikZ (más precisamente, los numerosos hipervínculos que contiene) con la documentación HTML no parece plantear problemas significativos debido a la existencia de varios paquetes y correcciones para incorporar una imagen de TikZ en HTML (por ejemplo, TeX4ht).

La cuestión del mantenimiento futuro de las guías dentro de SciPy se puede resolver fácilmente con Overleaf (facilita la colaboración y ofrece una vista previa instantánea) y las plantillas predefinidas que te proporcionaré. Básicamente, es probable que las guías gráficas no difieran mucho entre sí. La estructura, la paleta de colores y las formas serán, más o menos, invariables, por lo que no será un problema volver a darles forma y personalizarlas más adelante.

(Consulta la versión completa de la propuesta, disponible en la carpeta compartida de GSoD).