En esta página, se incluyen 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:
- NumPy
- Redactor técnico:
- cooperrc
- Nombre del proyecto:
- Documentación de NumPy para la educación comunitaria
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Introducción
NumPy ofrece un procesamiento basado en arrays limpio y rápido en una biblioteca de software de código abierto y gratuita. Es un paquete fundamental de la pila de SciPy para la computación científica [1]. Más de 370,000 proyectos lo usan para la computación de arrays eficiente [2]. Los usuarios de NumPy reciben un nuevo sitio web con aplicaciones y casos de éxito [1]. Cuando un usuario nuevo encuentra la página de documentación, se encuentra con varios vínculos "Comienza aquí" y con tutoriales introductorios que pueden resultar abrumadores para los principiantes, como NumPy Basics/byte-swapping. Comencé a usar NumPy hace diez años en la escuela de posgrado. Me encontré armando entradas de blog, notas de la clase y respuestas de StackExchange para evitar revisar la documentación de NumPy. Actualmente, hay más de 360,000 conversaciones de StackExchange relacionadas con NumPy. Imagino que otros usuarios tuvieron rutas similares al éxito en NumPy. Los componentes básicos de las herramientas educativas son la comunicación y la comunidad [4]. La documentación debe establecer una comunidad que refleje los objetivos deseados del proyecto. La documentación debe ser una guía coherente y clara para un usuario nuevo. Los instructivos deben proporcionar a los usuarios nuevos pasos fáciles de seguir y generar confianza en la biblioteca [3]. La documentación debe darle la bienvenida a un usuario nuevo a la comunidad de NumPy. La estructura, el ritmo y los autores de la documentación deben crear un lugar que favorezca la exploración y la comunicación. Esta propuesta organizará y completará las brechas en la documentación actual de NumPy para que los usuarios nuevos reciban educación y se integren a la comunidad.
El conocimiento que comunican los usuarios se obtiene a través de pruebas y experimentos [4,5]. El conocimiento depende del método de prueba y evaluación. El contenido que proporciona objetivos y aplicaciones claros en instructivos permite que los usuarios prueben y evalúen nuevas ideas y métodos. La comunidad puede crear una base de conocimiento para mejorar las habilidades, los datos y las aplicaciones. El espacio de instrucciones proporciona un beneficio doble. En primer lugar, los usuarios nuevos y experimentados tienen un conjunto de objetivos claros para probar y crear experimentos. En segundo lugar, los posibles colaboradores de documentación tienen un espacio para comunicar sus objetivos, métodos y soluciones. El espacio de instructivos satisface una necesidad inmediata de hacer que la documentación de NumPy sea más accesible para los usuarios nuevos y posibles colaboradores. Conocimiento actual
John Dewey dijo que la base del aprendizaje es una experiencia genuina [4]. La comunidad de NumPy tiene una gran cantidad de experiencia genuina que se puede compartir con otros usuarios. La educación se basa en la comunidad y la comunicación. Una página de documentación organizada es el lugar donde los usuarios nuevos pueden experimentar NumPy. También crea una plantilla estructurada para que los posibles colaboradores comuniquen experiencias en NumPy.
Existen cuatro espacios agrupados de forma general para la documentación de software [3]: espacio de instructivo, espacio de instructivo, espacio de explicación y espacio de referencia. La documentación de NumPy tiene varios documentos en el espacio de instructivos que combinan explicaciones y contenido de instructivos. El espacio del instructivo debe enfocarse en la educación del usuario y usar pasos fáciles de repetir para comunicar ideas. El espacio de instructivos proporciona procedimientos más orientados a objetivos que los usuarios pueden aplicar en aplicaciones del mundo real. El espacio de explicación proporciona información detallada sobre las cadenas de documentos en cada función. Los espacios de instructivos y guías prácticas actuales no están claramente delimitados y, a veces, se incluyen en el espacio de explicación y referencia. Hay un excelente instructivo para principiantes y una gran referencia para que los usuarios de Matlab compilen código NumPy en “Numpy para usuarios de Matlab”. Delinear claramente estos cuatro espacios hace que la documentación sea más clara.
Falta en la base de conocimiento/necesidad no satisfecha
La documentación actual abarca muchos temas necesarios, pero carece de una distinción clara entre los instructivos, los instructivos paso a paso, las explicaciones y los espacios de referencia. Esto genera confusión para los posibles colaboradores. Los usuarios nuevos pueden verse abrumados por las explicaciones y el material de referencia en la sección de tutoriales y los posibles colaboradores se enfrentan a obstáculos para contribuir. Propongo un diseño más accesible para los recién llegados y posibles colaboradores de documentación con un flujo lógico en la documentación y la administración de solicitudes de extracción para documentos instructivos que los usuarios hayan creado. Mi objetivo a largo plazo es crear una comunidad de documentación para que aprender de ella sea una experiencia de educación y comunicación en la que todos aporten. Este modelo de documentación basará la educación en la experiencia real para los recién llegados y los posibles colaboradores.
Razones
Esta propuesta de Google Summer of Docs es importante para mis objetivos pedagógicos y profesionales. Uso NumPy y SciPy en todos mis cursos. A mis estudiantes les resulta difícil navegar por la documentación actual. Quiero usar mi experiencia enseñando a programar a estudiantes que no se especializan en CS para ayudar a organizar, editar y completar los instructivos actuales. Luego, puedo usar la documentación como libro de texto y material de referencia para mis cursos. He creado docenas de tutoriales, ejercicios y ejemplos utilizando Python y
Objetivos específicos
Tengo tres objetivos específicos para esta propuesta de Google Summer of Docs: 1. Organiza la documentación actual. 2. Edita los instructivos actuales (Guía para principiantes, Creación de arrays, Indexación, Álgebra lineal y NumPy para Matlab) para mover la información de referencia al espacio de explicación. Crea materiales instructivos con los estudiantes. Cada objetivo específico tiene un resultado esperado para la propuesta.
Estos tres objetivos específicos tienen como objetivo hacer que la documentación sea más atractiva para los usuarios nuevos y proporcionar estructura a los posibles colaboradores. Los objetivos también ayudan a lograr el objetivo a largo plazo de seguir haciendo crecer la comunidad de documentación de NumPy. Resultados esperados
Tengo tres resultados esperados: 1. Una página web de documentación revisada que separa claramente los cuatro espacios: instructivos, instructivos, explicaciones y referencias, 2. instructivos nuevos para leer y escribir arrays, crear arrays (np.zeros, np.ones, np.block, etc.) y operaciones de algebra lineal en NumPy en comparación con las operaciones por elementos, y 3. un espacio de instructivos seleccionados.
Estos resultados esperados ayudarán a los usuarios nuevos a avanzar en los documentos, proporcionar a los posibles colaboradores de documentación estilos y formatos claros, hacer que los instructivos actuales sean más cortos y fáciles de seguir, mover las explicaciones a una sección separada y los nuevos colaboradores de documentación podrán contribuir con pequeños casos de uso a la sección de instructivos sin compilar toda la documentación de Sphinx. Queremos seguir construyendo nuestra comunidad de enseñanza y aprendizaje.
Los nuevos colaboradores de documentación pueden contribuir con casos de uso pequeños a millones de usuarios sin compilar toda la documentación de Sphinx. Queremos seguir construyendo nuestra comunidad de enseñanza y aprendizaje. Esta documentación propuesta imitará la documentación actual de código abierto, como Matplotlib, Divio, etc. A los usuarios nuevos y a los posibles colaboradores les resultará más fácil aprender a aplicar NumPy en sus campos y software.
El cronograma del proyecto es del 14/9 al 30/11. El primer paso es crear la documentación y separar el contenido de los instructivos actuales en contenido de instructivo, instructivo paso a paso y explicación. Esto se hará en las primeras cinco semanas del proyecto como parte de los resultados 1 y 2: revisar el sitio web y los instructivos, respectivamente. La organización de la documentación propuesta se muestra en la siguiente documentación propuesta.
Documentación propuesta:
i.Tutorials:
- Conceptos básicos absolutos para principiantes (quitar la instalación, ¿se puede reemplazar la importación/exportación de pandas por numpy.loadtxt?)
- vínculo a “¿Qué es NumPy?”
- Vínculo a las instrucciones básicas de instalación aquí
- Instructivo de inicio rápido (destinado a un seguimiento del instructivo de Python)
- Trabaja con arrays de NumPy
- Creación de arrays (np.zeros, np.ones, np.block, etcétera) (escribir: prioridad media-baja)
- Operaciones en términos de elementos (+,-,*,/) y operaciones de álgebra lineal (+,-,@, linalg.solve) (prioridad de escritura:media)
- Lee y escribe datos con NumPy (escritura: prioridad alta)
- Indexación
ii. Instructivos:
- Álgebra lineal en arrays n-dimensionales (me encantaría editar los encabezados y las descripciones, y tal vez cambiar el título a “Procesamiento de imágenes con álgebra lineal de Numpy”)
- vínculo al contenido instructivo de numpy-tutorials (trabajo en curso)
iii. Explicación:
- Tipos de datos
- E/S con NumPy
- Indexación
- Transmisión
- Intercambio de bytes
- Arrays estructurados
- Cómo escribir contenedores de arrays personalizados
- Creación de subclases de ndarray
- Varios
iv. Espacio de referencia:
- Glosario
- Referencia de la API de Numpy
- Numpy para usuarios de Matlab (la tabla de equivalencia es una excelente tabla de referencia, pero el análisis de arrays/matrices es molesto y parece obsoleto)
Después de completar esta temporada de Documentos de Google, propongo los siguientes resultados:
- Una página web de documentación revisada que separa claramente los cuatro espacios: instructivos, instructivos, explicaciones y referencias
- Instructivos nuevos para la creación de arrays (np.zeros, np.ones, np.block, etc.), operaciones a nivel de elementos (+,-,*,/) y operaciones de álgebra lineal (+,-,@, linalg.solve) y lectura y escritura de datos con Numpy (prioridad alta)
- Se recomendaron documentos instructivos para aumentar las contribuciones de los usuarios y ayudar a lograr los objetivos de la comunidad en la enseñanza y el aprendizaje
Cada resultado tiene una serie de pasos que se describen a continuación en las tablas de los resultados 1 a 3. Mientras se envía la documentación propuesta para su revisión, se escribirá el instructivo de alta prioridad “Arrays de lectura y escritura” para enviarlo como una solicitud de extracción como parte del resultado 2. Durante la revisión del sitio web corregido y el instructivo actualizado “Leer y escribir arrays”, comenzaré a escribir un instructivo para crear arrays con funciones de NumPy, p.ej., np.ones, np.zeros y np.diag. El tiempo restante se usará para responder los problemas de las solicitudes de extracción y comenzar a escribir la guía de nivel 3: Operaciones de algebra lineal y por elementos en Python.
El tercer resultado es aconsejar a los estudiantes de la Universidad de Connecticut que creen documentación en el repositorio de numpy-tutorials. Los instructivos o documentos enviados serán notebooks de Jupyter que usen NumPy para resolver problemas de ingeniería. Usaré algunas de mis notas o ejemplos del curso para enviar un notebook de ejemplo. Les recomendaré a los estudiantes que sigan el diseño y la estructura a medida que creamos una plantilla y un esquema de enmarcado. Este resultado ofrece una experiencia genuina para que los estudiantes comuniquen conceptos y soluciones a un público más amplio. Es una gran oportunidad para que los estudiantes se involucren con la comunidad de NumPy y aprendan.
Resultado 1: Revisar el sitio web Fecha de entrega Fork Repository and Build Docs with Sphinx 9/21 Build Webpage with Four Spaces defined and linked 10/1 Move current tutorials into appropriate spaces and Build docs 10/10 Submit PR to github with proposed changes 11/1 Respond to comments/suggestions and revise PR ongoing with Outcome 2 Website revised 11/30
Resultado 2: Revisa los instructivos Fecha de entrega Revisa la clasificación de revisión de los instructivos 9/21 Separa el contenido actual del instructivo en espacios de instructivo y explicación 10/1 Escribe la clasificación 1: Arreglos de lectura y escritura 10/10 Envía la PR a GitHub para su separación y revisión 10/20 Escribe la PR de clasificación 2: Creación de arrays 11/15 Escribe la PR de clasificación 3: Operaciones de algebra lineal y por elementos 11/30
Clasificación propuesta de las revisiones de instructivos (sujeta a cambios según los mentores o la comunidad):
Página actualmente vacía de los arrays de lectura/escritura
Creación de arrays (np.zeros, np.ones, np.block, etcétera) No existe: Ayudaría a los usuarios nuevos a que se expliquen y demuestren las herramientas comunes de interacción y creación de arrays.
Las operaciones de álgebra lineal y en sentido de elementos (+,-,*,/ y +,-@,linalg.solve) No existen: esto es muy útil para 1. Usuarios de Matlab y 2. Personas que adoptan el álgebra lineal (aprendizaje automático, regresión lineal, etcétera)
Resultado 3: Espacio de instructivos seleccionados Fecha de entrega Vínculo externo(problema o ejemplo)
Crea un ejemplo de instructivo (candidato: Cómo encontrar frecuencias naturales de las cuerdas de guitarra 10/20
Crea una plantilla de instructivo para colaboradores nuevos 10/1 en curso Relaciones públicas y enmarcado de posibles contribuciones de la plantilla de instructivos
Trabaja con otros colaboradores para crear notebooks de instructivos para reclutar estudiantes de la UConn y otros miembros de la comunidad Estado del 1/7: Se aprobó el trabajo-estudio y llegan las solicitudes
Importancia esperada
Esta propuesta de Google Summer of Docs hará la documentación de NumPy, completará los tutoriales faltantes del sitio web y obtendrá colaboradores de documentación. Como profesor de Ingeniería Mecánica, pienso segmentar la documentación de modo que mis estudiantes puedan navegar por los documentos y encontrar fácilmente instructivos introductorios en lugar de guías prácticas. La documentación segmentada (instructivo, instructivo, referencia y explicación) les brindará ejemplos estructurados a los posibles colaboradores para que creen nuevos recursos. La documentación propuesta se presta a un intercambio a través de la experiencia de educación y comunicación para usuarios nuevos y experimentados. El documento instructivo propuesto que asesora a los estudiantes de la Universidad de Connecticut pondrá en práctica esta idea de educación y comunicación. Queremos que todos los usuarios encuentren espacio para experimentar, aprender y unirse a la comunidad de NumPy.
Referencias
- Se accedió al sitio web de NumPy.org en julio de 2020.
- Repositorio de NumPy en GitHub.
- El sistema de documentación. Se accedió a Divio.com en julio de 2020.
- Dewey, John. Democracia y educación. Project Gutenberg, agosto de 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.