Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.
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 procesamiento rápido y limpio basado en arrays en una biblioteca de software de código abierto gratuita. Es un paquete fundamental de la pila SciPy para el procesamiento científico [1]. Se usan más de 370,000 proyectos para lograr un procesamiento de array eficiente[2]. Los usuarios de NumPy ven un nuevo sitio web con aplicaciones y casos de éxito [1]. Cuando un usuario nuevo encuentra la página de documentación, encuentra instructivos múltiples y vínculos de “Comienza aquí” que pueden ser abrumadores para un principiante, como NumPy Basics/swapping. Comencé a usar NumPy hace diez años en la universidad. Me encontré reuniendo 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 que tratan con NumPy. Me imagino que otros usuarios han tenido rutas similares hacia el é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 coherente y clara para un usuario nuevo. Los instructivos deben proporcionar a los usuarios nuevos pasos fáciles de seguir y crear comodidad con 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 fomente la exploración y la comunicación. Esta propuesta organizará y llenará los vacíos en la documentación actual de NumPy para que los nuevos usuarios sean educados y bienvenidos en la comunidad.
El conocimiento que comunican los usuarios se obtiene probando y experimentando [4,5]. El conocimiento depende del método de prueba y evaluación. El contenido que proporciona objetivos y aplicaciones claros en los instructivos permite a los usuarios probar y evaluar nuevas ideas y métodos. La comunidad puede crear una base de conocimiento que mejore las habilidades, los hechos y las aplicaciones. El espacio de instructivos ofrece un beneficio doble. En primer lugar, los usuarios nuevos y los 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 la necesidad inmediata de hacer que la documentación de NumPy sea más accesible para 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 despeja el camino para que los usuarios nuevos experimenten NumPy. También crea una plantilla estructurada para que posibles colaboradores comuniquen tus experiencias en NumPy.
Hay cuatro espacios amplios agrupados para la documentación de software [3]: espacio de tutorial, espacio de instructivos, espacio de explicación y espacio de referencia. La documentación de NumPy contiene varios documentos en el espacio del instructivo que mezclan explicaciones y contenidos prácticos. El espacio de los tutoriales debe centrarse en la educación del usuario y utilizar pasos fáciles de repetir para comunicar ideas. Este espacio proporciona procedimientos más orientados a los objetivos que los usuarios pueden aplicar en las aplicaciones del mundo real. El espacio de explicación proporciona información detallada y cadenas de documentos detalladas en cada función. Los espacios de instructivos y instructivos actuales no están claramente delimitados y, a veces, entran en el espacio de explicación y referencia. Hay un excelente instructivo para el nivel principiante absoluto, y hay una excelente referencia para que los usuarios de Matlab compilen código NumPy en "NumPy para usuarios de Matlab". Si delineas claramente estos cuatro espacios, la documentación será más clara.
Falta en la base de conocimientos/necesidad insatisfecha
La documentación actual abarca muchos temas necesarios, pero carece de una distinción clara entre instructivos, instructivos, explicaciones y espacios de referencia. Esto genera confusión para los posibles colaboradores. Los usuarios nuevos pueden sentirse abrumados por las explicaciones y el material de referencia de la sección del tutorial, y los posibles colaboradores deben enfrentarse a dificultades para contribuir. Propongo un diseño más accesible para los principiantes y posibles colaboradores de documentación con un flujo lógico en la documentación y la gestión de las solicitudes de extracción para los documentos instructivos que aportan los usuarios nuevos. Mi objetivo a largo plazo es desarrollar una comunidad de documentación para que aprender de ella sea una experiencia de comunicación y de dar y tomar. Este modelo de documentación basará la formación en la experiencia real para los nuevos usuarios y los posibles colaboradores.
Justificación
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 otras personas que no son de Informática para organizar, editar y llenar vacíos en los instructivos actuales. Luego, puedo usar la documentación como libro de texto y material de referencia para mis cursos. Creé decenas de instructivos, ejercicios y ejemplos usando Python y
Objetivos específicos
Tengo tres objetivos específicos para esta propuesta de Google Summer of Docs: 1. Organizar 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) a fin de mover información de referencia al espacio de explicación. 3. Crear materiales instructivos con los alumnos 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 acogedora para los usuarios nuevos y proporcionar una estructura a los posibles colaboradores. Los objetivos también ayudan a promover el objetivo a largo plazo de continuar expandiendo 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: cómo leer y escribir arrays, creación de arrays (np.zeros, np.ones, np.block, etc.) y operaciones de álgebra lineal en elementos frente a NumPy y 3. un espacio de instructivos seleccionado.
Estos resultados esperados ayudarán a los usuarios nuevos a avanzar en los documentos, proporcionar posibles colaboradores de documentación con estilos y formatos claros, hacer que los instructivos actuales sean más breves y fáciles de seguir, mover las explicaciones a una sección separada y los nuevos colaboradores de documentación podrán aportar pequeños casos de uso a la sección de instructivos sin tener que compilar toda la documentación de Sphinx. Queremos seguir desarrollando nuestra comunidad de enseñanza y aprendizaje.
Los nuevos colaboradores de documentación pueden contribuir con casos de uso pequeños para millones de usuarios sin necesidad de compilar toda la documentación de Sphinx. Queremos seguir desarrollando nuestra comunidad de enseñanza y aprendizaje. La documentación propuesta imitará la documentación actual de código abierto, como Matplotlib, Divio, etc. Los usuarios nuevos y los posibles colaboradores tendrán más tiempo para aprender a aplicar NumPy en sus campos y software.
El cronograma para el proyecto es del 14/9 al 30/11. El primer paso es compilar la documentación y separar el contenido de los instructivos actuales en contenido de instructivos, instructivos y explicaciones. Esto se hará durante las primeras cinco semanas del proyecto como parte de los resultados 1 y 2 en la revisión del sitio web y los instructivos, respectivamente. La organización de la documentación propuesta se muestra en la Documentación propuesta a continuación.
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 de instalación básicas aquí
- Instructivo de inicio rápido (destinado a un seguimiento del instructivo de Python)
- Trabaja con arrays NumPy
- creación de arrays (np.zeros, np.ones, np.block, etcétera) (escritura: prioridad media-baja)
- operaciones a nivel de elementos (+,-,*,/) y operaciones de álgebra lineal (+,-,@, linalg.solve) (prioridad write:med)
- Lee y escribe datos con Numpy (escritura: prioridad alta)
- Indexación
ii. Instructivos:
- Álgebra lineal en matrices n-dimensionales (te encantaría editar los encabezados y las descripciones, y quizás cambiar el título a "Procesamiento de imágenes con el á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
- Transmitiendo
- Intercambio de bytes
- Arrays estructurados
- Escribe contenedores de arrays personalizados
- subclasificación de ndarray
- Varios
iv. Espacio de referencia:
- Glosario
- Referencia de la API de NumPy
- NumPy para los usuarios de Matlab (la tabla de equivalencias es una gran tabla de referencia, pero el análisis de arrays y matrices nos distrae y parece obsoleto)
Una vez finalizada esta temporada de Documentos de Google, propongo los siguientes resultados:
- Una página web revisada de documentación que separa claramente los cuatro espacios: instructivos, instructivos, explicaciones y referencia.
- 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)
- Asesora documentos prácticos para aumentar las contribuciones de los usuarios y ayudar a promover los objetivos de la comunidad en la enseñanza y el aprendizaje
Cada resultado cuenta con una serie de pasos que se describen a continuación en las tablas de los resultados 1 a 3. Mientras la documentación propuesta se envía para su revisión, el instructivo de alta prioridad “arrays de lectura/escritura” se escribirá para su envío como una solicitud de extracción como parte del resultado 2. Durante la revisión del sitio web revisado y del instructivo actualizado “Leer/escribir arrays”, comenzaré a escribir un instructivo para crear arrays con las funciones NumPy, p.ej., np.ones, np.zeros, np.diag. El tiempo restante se usará para responder a problemas de solicitudes de extracción y comenzar a escribir el instructivo de rango 3: operaciones de álgebra lineal y por elementos en Python.
El tercer resultado es aconsejar a los estudiantes de la University of Connecticut para que creen documentación en el repositorio de NumPy-tutorials. Los instructivos o documentos prácticos enviados serán notebooks de Jupyter que usan NumPy para resolver problemas de ingeniería. Usaré algunas de las notas o ejemplos de mi curso para enviar un {i>notebook<i} de ejemplo. Les recomendaré a los alumnos que sigan el diseño y la estructura mientras creamos una plantilla y un esquema de enmarcado. Este resultado ofrece una experiencia genuina para que los alumnos comuniquen conceptos y soluciones a un público más amplio. Es una gran oportunidad para que los alumnos se involucren en la comunidad de NumPy y aprendan.
Resultado 1: Revisa el sitio web Deliverable Date Repository and Build Docs with Sphinx 9/21. Crea la página web con cuatro espacios definidos y vinculado 10/1 Mueve los instructivos actuales a los espacios adecuados y crea documentos 10/10 Envía RR.PP. a GitHub con cambios propuestos 11/1 Responde a comentarios/sugerencias en curso y revisa el RR.PP./sugerencias en curso con el resultado 2. Resultado 2
Resultado 2: Revisa los instructivos Fecha de entrega Revisar la clasificación de revisión 9/21 Separar el contenido del instructivo actual en los espacios de instructivos y explicaciones 10/1 Escribir la clasificación 1: Read/Write arrays 10/10 Enviar PR a github para separación y revisión 10/20 Escribir la clasificación 2: Creación de arrays PR 11/15 Escribir el rango 3: Operaciones lineales PR 11/15
Clasificación propuesta de las revisiones de tutoriales (sujetas a cambios según los mentores o la comunidad):
Por el momento, una página vacía de 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 explicar y demostrar las herramientas comunes de interacción/creación de arrays.
Las operaciones de álgebra lineal y por elementos (+,-,*,/ y +,-@,linalg.solve) no existen: esto es especialmente útil para 1. usuarios de Matlab y 2. Personas que adoptan para el álgebra lineal (aprendizaje automático, regresión lineal, etcétera)
Resultado 3: Espacio de instructivos seleccionado Fecha de entrega Vínculo externo(problema/ejemplo)
Crea un ejemplo de instructivo (candidato: Cómo encontrar frecuencias naturales de cuerdas de guitarra 10/20)
Crear una plantilla de instructivos para nuevos colaboradores 10/1 en curso Plantilla de instructivo - RR.PP. y encuadre de posibles contribuciones
Trabaja con otros colaboradores para crear {i>notebooks<i} sobre el trabajo y reclutamiento de solicitudes de miembros de UConn7.
Importancia esperada
Esta propuesta de Google Summer of Documentos hará que la documentación de NumPy, complete los instructivos faltantes del sitio web y obtenga colaboradores de documentación. Como profesor de Ingeniería Mecánica, pienso segmentar la documentación para 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, instructivos, referencia y explicación) proporcionará a los posibles colaboradores ejemplos estructurados para crear nuevos recursos. La documentación propuesta se presta al sacrificar el coto a través de una experiencia de educar y comunicar para usuarios nuevos y experimentados. El documento instructivo propuesto pondrá en práctica esta idea de educar y comunicar a los estudiantes de la University of Connecticut. Queremos que todos los usuarios encuentren espacio para experimentar, aprender y unirse a la comunidad de NumPy.
Referencias
- Sitio web NumPy.org; fecha de acceso: 07/2020
- Repositorio de NumPy en GitHub.
- El sistema de documentación Divio.com fecha de acceso: 07/2020.
- Dewey, John. Democracia y educación. Proyecto Gutenberg, agosto de 2015.
- Dewey, John. Misión de Certainty George Allen y Unwin Limited. 06/2005.