Proyecto SciPy

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:

SciPy

Escritor técnico:

mkg33

Nombre del proyecto:

Documentación orientada a los usuarios y reestructuración exhaustiva

Duración del proyecto:

Duración estándar (3 meses)

Project description

Motivación:

Tengo la intención de trabajar en la refactorización de la documentación existente para que sea de fácil acceso para usuarios con diferentes necesidades. No hace falta decir que lo más probable es que un investigador esté interesado en funciones avanzadas y sutiles, mientras que un usuario sin experiencia previa aprecia las guías y los diagramas paso a paso.

Me interesa participar en este proyecto por razones personales y profesionales. En primer lugar, me gustaría contribuir significativamente a SciPy porque mi propia investigación se benefició enormemente de ella y, en segundo lugar, encuentro documentación insuficiente (o la falta) con demasiada frecuencia en otro software y siempre me pregunto cuánto más rápido (si todo) podrían aprender a usar el código si hubieran recibido una guía completa.

Objetivos:

Mi objetivo es mejorar la documentación de SciPy existente tanto en términos de contenido como de gráficos. La característica más importante de mi enfoque para este problema es la implementación y el análisis de la encuesta de usuarios, es decir, una breve encuesta en línea que permite a varios usuarios expresar sus necesidades con respecto a la documentación. Creo firmemente que sus opiniones deberían ser la 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 consistirá en diseñar y analizar la encuesta de usuarios, así como abordar varios problemas estilísticos que he notado en la documentación actual. Por ejemplo, falta de coherencia (como los arrays bidimensionales junto con arrays bidimensionales), oraciones convoluciones que deben reescribirse o la falta de orden alfabético en ciertas subpáginas. La segunda fase se centrará en la introducción de guías gráficas que contienen hipervínculos a los temas relevantes (según los resultados de la encuesta y otras solicitudes de la comunidad). A largo plazo, deseo conseguir una documentación satisfactoria adaptada a diferentes tipos de usuarios. Además, intentaré hacer que los instructivos sean más coherentes en términos lingüísticos y estructurales. Por último, pero no menos importante, mi objetivo es escribir nuevos tutoriales (en función de las necesidades actuales de la comunidad).

Encuesta para usuarios:

En lo que respecta a la encuesta para usuarios, propongo usar Formularios de Google por varios motivos. 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 fines de análisis estadístico. Según investigaciones 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, usar un producto de Google en una iniciativa administrada por Google sería un gesto amable.

Creé una encuesta preliminar con preguntas de ejemplo (puedes acceder a ella en https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Una cantidad razonable de preguntas en la versión final debe ser 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 debería parecerse a un espectro completo (solo provoca confusión y es probable que los resultados tengan una alta dispersión). Debe haber un máximo de dos preguntas abiertas; de lo contrario, los resultados estarán muy dispersos y no serán útiles para nada. Creo que incluso un número muy alto de respuestas no sería problemático debido al hecho de que los datos se pueden exportar fácilmente y analizar automáticamente con software estadístico. Suponiendo que el número de respuestas es, de hecho, muy alto, el análisis de las preguntas abiertas puede llevar un poco de tiempo, pero supongo que no será abrumador. Después de todo, es probable que un usuario común no escriba un ensayo sobre el estado de la documentación. En el peor de los casos, algunas respuestas pueden almacenarse simplemente para análisis futuros.

Guías gráficas:

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

En cuanto a los detalles de la implementación, propongo usar el paquete TikZ. En primer lugar, es una herramienta poderosa y no parece correr el riesgo de que pronto deje de estar disponible. También ofrece resultados de alta calidad, tiene una documentación muy sólida y es un tema frecuente en TeX StackExchange y en otros foros comunes. Lo más importante es que la integración de un archivo TikZ (lo que es más precisamente, los numerosos hipervínculos que hay allí) con documentación HTML no parece suponer 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 futuro mantenimiento de las guías en SciPy se puede resolver fácilmente usando, por ejemplo, Overleaf (facilita la colaboración y ofrece una vista previa instantánea) y las plantillas predefinidas que proporcionaré. Básicamente, es poco probable que las guías gráficas difieran demasiado entre sí. La estructura, la paleta de colores y las formas serán, en mayor o menor medida, invariables, por lo que la modificación posterior y la personalización adicional no serán un problema.

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