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:
- NumPy
- Escritor técnico:
- cooperrc
- Nombre del proyecto:
- Documentación de NumPy para la educación de la comunidad
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Introducción
NumPy ofrece procesamiento limpio y rápido 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 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 enlaces de "Comienza aquí" y tutoriales introductorios que pueden ser abrumadores para un principiante, como Conceptos básicos de NumPy/intercambio de bytes. Comencé a usar NumPy hace diez años en un posgrado. Me encontré con entradas de blog, notas de la clase y respuestas de StackExchange para evitar leer la documentación de NumPy. Actualmente, hay más de 360,000 conversaciones de StackExchange relacionadas con NumPy. 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 una guía coherente y clara para un usuario nuevo. Los instructivos deben brindarles a los usuarios nuevos pasos fáciles de seguir y crear comodidad con la biblioteca [3]. En la documentación, se debe dar la bienvenida a un usuario nuevo a la comunidad de NumPy. La estructura, el ritmo y los autores de la documentación necesitan crear un lugar que acoja la exploración y la comunicación. Esta propuesta organizará y llenará vacíos en la documentación actual de NumPy para que los usuarios nuevos reciban educación y la bienvenida a la comunidad.
El conocimiento que comunican los usuarios se adquiere 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 los instructivos les permite a los usuarios probar y evaluar nuevas ideas y métodos. La comunidad puede crear una base de conocimiento para mejorar sus habilidades, hechos y aplicaciones. El espacio de instructivos proporciona 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 cubre 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 cuenta con una enorme 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 los posibles colaboradores comuniquen tus experiencias en NumPy.
Hay cuatro espacios ampliamente agrupados para la documentación del software [3]: espacio para instructivos, espacio para instructivos, espacio para explicaciones y espacio de referencia. En la documentación de NumPy, hay varios documentos disponibles en el instructivo que combinan explicación y contenido sobre cómo espaciar contenido en el instructivo. El espacio de tutoriales debe centrarse en la educación de los usuarios y utilizar pasos fáciles de repetir para comunicar ideas. El espacio de instructivos proporciona procedimientos más orientados a los objetivos que los usuarios pueden aplicar en aplicaciones en el mundo real. El espacio de explicación proporciona información detallada y strings de documentos detalladas en cada función. El instructivo y los espacios de instructivos actuales no están claramente delineados y, a veces, ingresan en el espacio de explicación y referencia. Hay un instructivo excelente para el "Principiante absoluto" y hay una gran referencia para que los usuarios de Matlab compilen código NumPy en "NumPy para usuarios de Matlab". Delinear claramente estos cuatro espacios, la documentación será más clara.
Brecha en la base de conocimiento/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 de tutoriales, y los posibles colaboradores se enfrentan a obstáculos para contribuir. Propongo un diseño más accesible para los principiantes y los posibles colaboradores de documentación con un flujo lógico en la documentación y la administración de las solicitudes de extracción para los documentos instructivos que contribuyen los usuarios nuevos. Mi objetivo a largo plazo es desarrollar la comunidad de documentación para que aprender de la documentación sea una experiencia de educar y comunicar de compromiso. Este modelo para la documentación basará la educación en la experiencia real para los nuevos usuarios y los posibles colaboradores.
Justificación
Esta propuesta de Google para el verano de Documentos es importante para mis objetivos pedagógicos y profesionales. Uso NumPy y SciPy en todos mis cursos. Mis alumnos tienen dificultades para navegar por la documentación actual. Quiero aprovechar mi experiencia enseñándole a personas que no son carreras 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 para el verano de Documentos: 1. Organizar la documentación actual, 2. Edita los instructivos actuales (Guía para principiantes, Creación de arreglos, Indexación, Álgebra lineal y NumPy para Matlab) a fin de mover la 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 el objetivo de hacer que la documentación sea más acogedora para los usuarios nuevos y proporcionar estructura a los posibles colaboradores. Los objetivos también ayudan a avanzar hacia el objetivo a largo plazo de continuar haciendo crecer la comunidad de documentación de NumPy. Resultados esperados
Tengo tres resultados esperados como tales: 1. una página web de documentación revisada que separa claramente los cuatro espacios: tutoriales, instructivos, explicación y referencia, 2. nuevos tutoriales para: arrays de lectura y escritura, creación de arrays (np.zeros, np.ones, np.block, etc.) y operaciones de álgebra lineal en cuanto a elementos en 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, reducir y seguir los instructivos actuales, 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 desarrollando nuestra comunidad de enseñanza y aprendizaje.
Los nuevos colaboradores de documentación pueden aportar pequeños casos de uso a millones de usuarios sin necesidad de compilar toda la documentación de Sphinx. Queremos seguir desarrollando nuestra comunidad de enseñanza y aprendizaje. Esta 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 Instructivos, Instructivos y Explicación. Esto se llevará a cabo durante las primeras cinco semanas del proyecto como parte de los resultados 1 y 2 en la revisión del sitio web y los tutoriales, 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 instalación, ¿se puede reemplazar y exportar 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.) (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 arreglos de n dimensiones (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 a 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 array personalizados
- subclasificación de ndarray
- Varios
iv. Espacio de referencia:
- Glosario
- Referencia de la API de Numpy
- NumPy para usuarios de Matlab (la tabla de equivalencias es una gran tabla de referencia, pero el análisis de array/matriz distrae a los usuarios 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, Explicación y Referencia.
- Nuevos instructivos: creación de arrays (np.zeros, np.ones, np.block, etc.), operaciones a nivel de elementos (+,-,*,/) y operaciones de álgebra lineal (+,-,@, linalg.solve), y operaciones de lectura y escritura de datos usando Numpy (prioridad alta)
- Asesoría documentos instructivos 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 tiene una serie de pasos que se describen a continuación en las tablas de los resultados 1-3. Si bien la Documentación propuesta se envía para su revisión, el instructivo de alta prioridad "arreglos 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 el instructivo actualizado de “Lectura/escritura de arreglos”, comenzaré a escribir un instructivo para crear arrays con 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 clasificación 3: operaciones de álgebra lineal y a nivel de elementos en Python.
El tercer resultado es aconsejar a los estudiantes de la University of Connecticut que compilen documentación en el repositorio de NumPy-tutorials. Los instructivos o documentos explicativos 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: Revisar sitio web Deliverable Date
Resultado 2: Revisar instructivos Fecha de entrega Revisar la clasificación de revisión 9/21 Separar el contenido actual del instructivo en los espacios de Instructivo y Explicación 10/1 Escribir la clasificación 1: Arreglos de lectura/escritura 10/10 Enviar PR a GitHub para la separación y revisión 10/20 Escribir la clasificación 2: Creación de arreglos PR 11/15 Escribir la clasificación PR 11/15 linear el rango PR 11/15 Escribir el rango PR 11/15
Clasificación propuesta de revisiones de tutoriales (sujeto a cambio según los mentores y la comunidad):
Página vacía de arrays de lectura/escritura actualmente
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 a nivel de los elementos (+,-,*,/ y +,-@,linalg.solve) no existen: esto es especialmente útil para 1. usuarios de Matlab y 2. Personas que adoptan el modelo de álgebra lineal (aprendizaje automático, regresión lineal, etc.)
Resultado 3: Espacio de instructivos seleccionado Fecha de entrega Vínculo externo(problema/ejemplo)
Crear 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 PR y encuadre posibles contribuciones
Trabajar con otros colaboradores para crear {i>notebooks<i} de ejercicios prácticos; reclutar miembros de UConn; reclutar a miembros de la comunidad; reclutar a estudiantes aprobados1
Importancia esperada
Esta propuesta para el verano de Google Docs hará que la documentación de NumPy, completará los instructivos que faltan del sitio web y conseguirá colaboradores de documentación. Como profesor de Ingeniería Mecánica, pienso segmentar la documentación para que mis alumnos puedan navegar por los documentos y encontrar fácilmente instructivos introductorios en lugar de guías prácticas. La documentación segmentada (instructivos, instructivos, referencias y explicaciones) ofrece a los posibles colaboradores ejemplos estructurados para crear nuevos recursos. La documentación propuesta se presta a un intercambio a través de una experiencia de educar y comunicar para usuarios nuevos y experimentados. El documento instructivo propuesto que se propone con los estudiantes de la University of Connecticut pondrá en práctica esta idea de educar y comunicar. Queremos que todos los usuarios encuentren espacio para experimentar, aprender y unirse a la comunidad de NumPy.
Referencias
- Sitio web NumPy.org de acceso el 07/2020.
- NumPy en el repositorio de GitHub.
- El sistema de documentación. Divio.com fecha de acceso: 07/2020.
- Dewey, John. Democracia y educación. Project Gutenberg, agosto de 2015.
- Dewey, John. Misión para Certainty George Allen And Unwin Limited. 06/2005.