Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- NumPy
- Redator técnico:
- cooperrc
- Nome do projeto:
- Documentação do NumPy para educação da comunidade
- Duração do projeto:
- Duração padrão (três meses)
Project description
Introdução
O NumPy oferece computação limpa e rápida baseada em matrizes em uma biblioteca de software de código aberto sem custo financeiro. É um pacote fundamental na pilha SciPy para computação científica [1]. Mais de 370 mil projetos usam para computação de matriz eficiente [2]. Os usuários NumPy são recebidos por um novo site com aplicativos e estudos de caso [1]. Quando um novo usuário encontra a página de documentação, ele encontra vários links "Comece por aqui" e tutoriais introdutórios que podem ser avassaladores para um iniciante, como os conceitos básicos do NumPy/troca de bytes. Comecei a usar o NumPy há dez anos na pós-graduação. Eu me vi juntando postagens de blog, anotações de aula e respostas do StackExchange para evitar ter que ler a documentação do NumPy. No momento, há mais de 360 mil conversas no StackExchange sobre NumPy. Imagino que outros usuários tenham tido caminhos semelhantes para o sucesso no NumPy. Os elementos básicos das ferramentas educacionais são comunicação e comunidade [4]. A documentação precisa estabelecer uma comunidade que reflita os objetivos desejados do projeto. A documentação precisa ser consistente e um guia claro para um novo usuário. Os tutoriais devem fornecer aos novos usuários etapas fáceis de seguir e familiarizar os usuários com a biblioteca [3]. A documentação precisa dar as boas-vindas a um novo usuário na comunidade do NumPy. A estrutura, o ritmo e os autores da documentação precisam criar um lugar que incentive a exploração e a comunicação. Esta proposta vai organizar e preencher as lacunas da documentação atual do NumPy para que novos usuários sejam informados e acolhidos na comunidade.
O conhecimento que os usuários comunicam é adquirido por meio de testes e experimentos [4,5]. O conhecimento depende do método de teste e avaliação. O conteúdo que oferece objetivos e aplicações claros em tutoriais permite que os usuários testem e avaliem novas ideias e métodos. A comunidade pode criar uma base de conhecimento para melhorar habilidades, fatos e aplicativos. O espaço de instruções oferece dois benefícios. Primeiro, usuários novos e experientes têm um conjunto de metas claras para testar e criar experimentos. Em segundo lugar, os possíveis colaboradores da documentação têm um espaço para comunicar as metas, os métodos e as soluções. O espaço de instruções atende a uma necessidade imediata de tornar a documentação do NumPy mais acessível para novos usuários e possíveis colaboradores. Conhecimento atual
John Dewey disse que a base da aprendizagem é uma experiência genuína [4]. A comunidade NumPy tem uma enorme quantidade de experiências verdadeiras que pode ser compartilhada com outros usuários. A educação se baseia na comunidade e na comunicação. Uma página de documentação organizada abre o caminho para novos usuários aproveitarem o NumPy. Ele também cria um modelo estruturado para que possíveis colaboradores comuniquem experiências no NumPy.
Há quatro espaços agrupados de forma ampla para a documentação de software [3]: espaço de tutorial, espaço de instruções, espaço de explicação e espaço de referência. A documentação do NumPy tem vários documentos no espaço do tutorial que misturam explicação e conteúdo de instruções no tutorial. O espaço do tutorial deve se concentrar na educação do usuário e usar etapas fáceis de repetir para comunicar ideias. O espaço de instruções fornece procedimentos mais orientados a objetivos que os usuários podem aplicar em aplicações do mundo real. O espaço de explicação oferece informações detalhadas de strings de documentos detalhadas em cada função. Os espaços de tutorial e de instruções atuais não são claramente delineados e às vezes entram no espaço de explicação e referência. Há um excelente tutorial para iniciantes e uma ótima referência para usuários do Matlab criarem código NumPy em "NumPy para usuários do Matlab". Delinear claramente esses quatro espaços torna a documentação mais clara.
Lacuna na base de conhecimento/necessidade não atendida
A documentação atual aborda muitos tópicos necessários, mas não tem uma distinção clara entre tutoriais, instruções, explicações e espaços de referência. Isso pode confundir os possíveis colaboradores. Os novos usuários podem se sentir sobrecarregados com as explicações e o material de referência na seção do tutorial, e os possíveis colaboradores enfrentam obstáculos para contribuir. Proponho um layout mais acessível para iniciantes e possíveis colaboradores com um fluxo lógico na documentação e gerenciamento de solicitações de envio para documentos de instruções fornecidos pelos usuários por novos colaboradores. Meu objetivo de longo prazo é criar a comunidade de documentação para que aprender com ela seja uma experiência de troca, educação e comunicação. Esse modelo de documentação vai fundamentar a educação na experiência real para os novatos e possíveis colaboradores.
Justificativa
Essa proposta do Google Summer of Docs é importante para meus objetivos pedagógicos e profissionais. Eu uso o NumPy e o SciPy em todos os meus cursos. A documentação atual é difícil de navegar para meus alunos. Quero usar minha experiência ensinando pessoas que não são da área de Ciência da Computação a programar para ajudar a organizar, editar e preencher lacunas nos tutoriais atuais. Depois, posso usar a documentação como um livro-texto e material de referência para meus cursos. Criei dezenas de tutoriais, exercícios e exemplos usando Python e
Objetivos específicos
Tenho três objetivos específicos para esta proposta do Google Summer of Docs: 1. Organize a documentação atual, 2. Editar os tutoriais atuais (Guia para iniciantes, criação de matrizes, indexação, álgebra linear e NumPy para Matlab) para mover as informações de referência para o espaço de explicação e 3. Crie materiais instrutivos com os estudantes. Cada objetivo específico tem um resultado esperado para a proposta.
Esses três objetivos específicos têm como objetivo tornar a documentação mais convidativa para novos usuários e fornecer estrutura para possíveis colaboradores. Os objetivos também ajudam a alcançar o objetivo de longo prazo de continuar crescendo a comunidade de documentação do NumPy. Resultados esperados
Tenho três resultados esperados: 1. Uma página da documentação revisada que separa claramente os quatro espaços: tutoriais, instruções, explicações e referência, 2. novos tutoriais para: leitura e gravação de matrizes, criação de matrizes (np.zeros, np.ones, np.block, etc.) e operações elementar x linear em NumPy e 3. um espaço de instruções selecionadas.
Esses resultados esperados vão ajudar os novos usuários a progredir nos documentos, fornecer aos possíveis colaboradores estilos e formatos claros, tornar os tutoriais atuais mais curtos e fáceis de seguir, mover explicações para uma seção separada e permitir que novos colaboradores contribuam com pequenos casos de uso para a seção de instruções sem criar a documentação completa do Sphinx. Queremos continuar construindo nossa comunidade de ensino e aprendizagem.
Novos colaboradores de documentação podem contribuir com pequenos casos de uso para milhões de usuários sem criar toda a documentação do Sphinx. Queremos continuar construindo nossa comunidade de ensino e aprendizagem. A documentação proposta vai imitar a documentação de código aberto atual, como Matplotlib, Divio etc. Novos usuários e possíveis colaboradores vão ter mais facilidade para aprender a aplicar o NumPy em seus campos e softwares.
O cronograma do projeto é de 14/9 a 30/11. A primeira etapa é criar a documentação e separar o conteúdo dos tutoriais atuais em conteúdo de tutorial, instruções e explicação. Isso será feito nas primeiras cinco semanas do projeto como parte dos Resultados 1 e 2, revisando o site e os tutoriais, respectivamente. A organização proposta da documentação é mostrada na documentação proposta abaixo.
Documentação proposta:
i.Tutorials:
- Noções básicas para iniciantes (remover instalação, a importação/exportação de pandas pode ser substituída por numpy.loadtxt?)
- link para “What is numpy”
- link para as instruções básicas de instalação aqui
- Tutorial de início rápido (para acompanhar o tutorial de Python)
- Como trabalhar com matrizes numpy
- criação de matrizes (np.zeros, np.ones, np.block etc.) (escreva: prioridade média-baixa)
- Operações elementais (+,-,*,/) e operações de álgebra linear (+,-,@, linalg.solve) (gravação:prioridade média)
- Ler e gravar dados usando numpy (gravação: alta prioridade)
- Indexação
ii. Tutoriais:
- Álgebra linear em matrizes n-dimensionais (gostaria de editar os títulos e descrições e talvez mudar o título para "Processamento de imagens com a álgebra linear do Numpy")
- link para o conteúdo de instruções do numpy-tutorials (trabalho em andamento)
iii. Explicação:
- Tipos de dados
- E/S com Numpy
- Indexação
- Transmissão
- Troca de bytes
- Matrizes estruturadas
- Como gravar contêineres de matrizes personalizados
- subclassificar ndarray
- Diversos
iv. Espaço de referência:
- Glossário
- Referência da API Numpy
- Numpy para usuários do Matlab (a tabela de equivalência é uma ótima tabela de referência, mas a discussão sobre matrizes/matrizes é distrativa e parece descontinuada)
Ao concluir esta temporada de documentos do Google, proponho os seguintes resultados:
- Uma página da Web de documentação revisada que separa claramente os quatro espaços: tutoriais, como fazer, explicação e referência
- Novos tutoriais para: criação de matrizes (np.zeros, np.ones, np.block etc.), operações elementais (+,-,*,/) e operações de álgebra linear (+,-,@, linalg.solve) e leitura e gravação de dados usando Numpy (alta prioridade)
- Orientou documentos de instruções para aumentar as contribuições dos usuários e ajudar a promover as metas da comunidade em ensino e aprendizado
Cada resultado tem um número de etapas descritas abaixo nas tabelas dos Resultados 1 a 3. Enquanto a documentação proposta é enviada para revisão, o tutorial de alta prioridade "Matrizes de leitura/gravação" será escrito para envio como uma solicitação de pull como parte do Resultado 2. Durante a revisão do site revisado e o tutorial atualizado de “Leitura/gravação de matrizes”, começarei a escrever um tutorial para criar matrizes usando funções numpy, por exemplo, np.ones, np.zeros, np.diag. O tempo restante será usado para responder a problemas de solicitação de envio e começar a escrever o tutorial de classificação 3: operações de álgebra linear e com elementos em Python.
O terceiro resultado é aconselhar os estudantes da Universidade de Connecticut a criar documentação no repositório numpy-tutorials. Os tutoriais ou documentos de instruções enviados serão notebooks do Jupyter que usam o NumPy para resolver problemas de engenharia. Vou usar algumas das minhas anotações/exemplos do curso para enviar um notebook de exemplo. Vou aconselhar os estudantes a seguir o layout e a estrutura enquanto criamos um modelo e um esquema de enquadramento. Esse resultado apresenta uma experiência genuína para os estudantes comunicarem conceitos e soluções para um público mais amplo. É uma ótima oportunidade para os alunos se envolverem com a comunidade do NumPy e aprender.
Resultado 1: revisar o site Data de entrega Criar um repositório e criar documentos com o Sphinx 9/21 Criar uma página da Web com quatro espaços definidos e vinculados 10/1 Mover os tutoriais atuais para os espaços apropriados e criar documentos 10/10 Enviar uma solicitação de revisão ao GitHub com as mudanças propostas 11/1 Responder aos comentários/sugestões e revisar a solicitação de revisão em andamento com o resultado 2 Revisão do site 11/30
Resultado 2: revisar tutoriais Data de entrega Classificação da revisão dos tutoriais 9/21 Separar o conteúdo do tutorial atual nos espaços "Tutorial" e "Explanation" 10/1 Escrever a classificação 1: ler/escrever matrizes 10/10 Enviar PR para o github para separação e revisão 10/20 Escrever a classificação 2: PR de criação de matrizes 11/15 Escrever a classificação 3: operações de álgebra linear e elementar PR 11/30
Classificação proposta das revisões de tutoriais (sujeita a mudanças de acordo com mentores/comunidade):
As matrizes de leitura/gravação estão atualmente vazias
Criação de matriz (np.zeros, np.ones, np.block, etc.) Não existe: ajudaria novos usuários a ter as ferramentas comuns de criação/interação de matrizes explicadas e demonstradas
Operações de álgebra linear e elementar (+,-,*,/ e +,-@,linalg.solve) não existem: isso é especialmente útil para 1. Usuários do Matlab e 2. Pessoas que adotam a álgebra linear (machine learning, regressão linear etc.)
Resultado 3: data de entrega selecionada para o espaço de instruções
Significado esperado
Esta proposta do Google Summer of Docs vai criar a documentação do NumPy, preencher tutoriais ausentes no site e ganhar colaboradores de documentação. Como professor de engenharia mecânica, pretendo segmentar a documentação de modo que os estudantes possam navegar pelos documentos e encontrar facilmente tutoriais introdutórios e guias práticos. A documentação segmentada: tutorial, instruções, referência e explicação vai oferecer aos possíveis colaboradores exemplos estruturados para criar novos recursos. A documentação proposta permite uma experiência de troca por meio de educação e comunicação para usuários novos e experientes. O documento de orientação proposto com os estudantes da Universidade de Connecticut vai colocar essa ideia de educação e comunicação em prática. Queremos que todos os usuários tenham espaço para experimentar, aprender e participar da comunidade NumPy.
Referências
- Site NumPy.org acessado em 07/2020.
- Repositório do NumPy no GitHub.
- O sistema de documentação. Acesso ao site Divio.com em julho de 2020.
- Dewey, John. Democracia e educação. Project Gutenberg, agosto de 2015.
- Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.