Esta página contém os detalhes de um projeto de escrita técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- NumPy
- Redator técnico:
- cooperrc
- Nome do projeto:
- Documentação NumPy para educação da comunidade
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Introdução
O NumPy oferece computação limpa e rápida baseada em matriz em uma biblioteca de software de código aberto sem custo financeiro. É um pacote fundamental da pilha SciPy para a computação científica [1]. Mais de 370 mil projetos usam para computação de matriz eficiente [2]. 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 recebe vários links “Comece aqui” e tutoriais introdutórios que podem ser difíceis para um iniciante, como noções básicas de NumPy/byte-swap. Comecei a usar o NumPy há dez anos na pós-graduação. Eu me vi reunindo postagens de blog, notas de aula e respostas do Stack Exchange para evitar ler a documentação do NumPy. Atualmente, há mais de 360 mil conversas do Stack Exchange que lidam com NumPy. Imagino que outros usuários tiveram rotas semelhantes para o sucesso com o NumPy. Os elementos básicos das ferramentas educacionais são a comunicação e o senso de comunidade [4]. A documentação precisa estabelecer uma comunidade que reflita as metas desejadas do projeto. A documentação deve ser um guia claro e consistente para novos usuários. Os tutoriais devem oferecer aos novos usuários etapas fáceis de seguir e criar conforto com a biblioteca [3]. A documentação precisa dar as boas-vindas a um novo usuário na comunidade NumPy. A estrutura, o ritmo e os autores da documentação precisam criar um espaço que agrade a exploração e a comunicação. Esta proposta vai organizar e preencher as lacunas da documentação atual do NumPy para que os novos usuários sejam instruídos e acolhidos na comunidade.
O conhecimento que os usuários comunicam é obtido por testes e experimentos [4,5]. O conhecimento depende do método de teste e avaliação. Conteúdo que apresenta metas e aplicações claras em instruções permite que os usuários testem e avaliem novas ideias e métodos. A comunidade pode construir uma base de conhecimento para aprimorar habilidades, fatos e aplicações. O espaço de instruções tem dois benefícios. Primeiro, os usuários novos e experientes têm um conjunto de metas claras para testar e criar experimentos. Segundo, possíveis colaboradores da documentação têm um espaço para comunicar objetivos, métodos e soluções. O espaço de instruções supre 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 do aprendizado é uma experiência genuína [4]. A comunidade NumPy tem uma enorme quantidade de experiência genuína 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 permite que novos usuários conheçam o numpy. Ele também cria um modelo estruturado para que possíveis colaboradores informem experiências com NumPy.
Há quatro espaços amplamente agrupados para 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 de NumPy tem vários documentos no espaço do tutorial que combinam o conteúdo de explicação e de "como espaçar" no tutorial. O espaço do tutorial deve se concentrar na instruçã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 metas que os usuários podem aplicar em aplicativos do mundo real. O espaço de explicação fornece strings de documentos detalhadas com informações detalhadas de cada função. O tutorial atual e os espaços de instruções não são claramente delineados e, às vezes, entram no espaço de explicação e referência. Há um excelente tutorial para o "Absoluto iniciante" e uma ótima referência para os usuários do Matlab criarem código Numpy no "Numpy para usuários do Matlab". A definição clara desses 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 distinção clara entre espaços de tutorial, instruções, explicação e referência. Isso pode confundir os possíveis colaboradores. Novos usuários podem se sentir sobrecarregados com a explicação e o material de referência da seção do tutorial, e os colaboradores em potencial terão dificuldade para contribuir. Proponho um layout mais acessível para iniciantes e possíveis colaboradores da documentação com um fluxo lógico na documentação e no gerenciamento de solicitações de envio de documentos de instruções fornecidos pelos usuários por novos colaboradores. Meu objetivo a longo prazo é construir a comunidade de documentação para que o aprendizado com a documentação seja uma experiência de educar e comunicar. Este modelo de documentação fundamentará o ensino na experiência real para novos colaboradores e novos colaboradores.
Justificativa
Esta proposta do Google Summer of Docs é importante para minhas metas pedagógicas e profissionais. Eu uso NumPy e SciPy em todos os meus cursos. Os estudantes têm dificuldade para navegar pela documentação atual. Quero usar minha experiência ensinando pessoas que não são de ciência da computação a programar para ajudar a organizar, editar e preencher as lacunas nos tutoriais atuais. Assim, posso usar a documentação como um livro didático e material de referência para meus cursos. Criei diversos tutoriais, exercícios e exemplos usando Python e
Objetivos específicos
Tenho três objetivos específicos para essa proposta do Google Summer of Docs: 1. Organizar a documentação atual; 2. Edite 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. Construir materiais de instruções com os estudantes. Cada objetivo específico tem um resultado esperado para a proposta.
Esses três objetivos específicos visam tornar a documentação mais acolhedora para novos usuários e fornecer estrutura para possíveis colaboradores. O objetivo também ajuda a promover o objetivo de longo prazo de continuar aumentando a comunidade de documentação numpy. Resultados esperados
Tenho três resultados esperados, como tais: 1. Uma página da Web de documentação revisada que separa claramente os quatro espaços: tutoriais, instruções, explicação 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ção de álgebra linear versus elemento em NumPy e 3. um espaço de instruções selecionado.
Esses resultados esperados ajudarão os novos usuários a avançar nos documentos, fornecer estilos e formatos claros à documentação, tornar os tutoriais atuais mais curtos e fáceis de seguir, mover as explicações para uma seção separada e os novos colaboradores da documentação poderão contribuir com pequenos casos de uso para a seção de instruções sem criar toda a documentação do Sphinx. Queremos continuar a construir nossa comunidade de ensino e aprendizagem.
Os novos colaboradores da documentação podem contribuir em pequenos casos de uso para milhões de usuários sem criar toda a documentação do Sphinx. Queremos continuar a construir nossa comunidade de ensino e aprendizagem. Esta documentação proposta imitará a documentação atual de código aberto, como Matplotlib, Divio etc. Novos usuários e possíveis colaboradores terão mais facilidade para aprender a aplicar o NumPy nos campos e software deles.
O cronograma do projeto é de 14/09 a 30/11. A primeira etapa é criar a documentação e separar o conteúdo dos tutoriais atuais em tutoriais, instruções e explicações. Isso será feito nas primeiras cinco semanas do projeto como parte dos Resultados 1 e 2, a revisão do site e dos tutoriais, respectivamente. A organização de documentação proposta é mostrada na Documentação proposta abaixo.
Documentação proposta:
i.Tutorials:
- Conceitos básicos absolutos para iniciantes (remover instalação. É possível importar/exportar o pandas ser substituído por numpy.loadtxt?)
- link para "O que é numpy"
- link para as instruções básicas de instalação aqui
- Tutorial de início rápido (para acompanhamento do tutorial do Python)
- Como trabalhar com matrizes numpy
- criação da matriz (np.zeros, np.ones, np.block etc.) (gravação: prioridade média-baixa)
- operações por elementos (+,-,*,/) e operações de álgebra linear (+,-,@, linalg.solve) (prioridade de write:med)
- Ler e gravar dados usando Numpy (gravação: alta prioridade)
- Indexação
ii. Instruções:
- Álgebra linear em matrizes n-dimensionais (adorariam editar os títulos e as descrições e talvez mudar o título para "Processamento de imagens com álgebra linear de Numpy")
- Link para o conteúdo de instruções numpy-tutorials (trabalho contínuo)
iii. Explicação:
- Tipos de dados
- E/S com Numpy
- Indexação
- Transmitindo
- Troca de bytes
- Matrizes estruturadas
- Como gravar contêineres de matriz personalizada
- como criar subclasses de 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 de matriz/matriz é uma distração e parece obsoleta)
Ao concluir esta temporada de Documentos Google, proponho os seguintes resultados:
- Uma página da Web de documentação revisada que separa claramente os quatro espaços: Tutoriais, Instruções, Explicação e Referência
- Novos tutoriais para: criação de matrizes (np.zeros, np.ones, np.block etc.), operações por elemento (+,-,*,/) e operações de álgebra linear (+,-,@, linalg.solve) e leitura e gravação de dados usando Numpy (prioridade alta)
- Orientou documentos de instruções para aumentar as contribuições dos usuários e ajudar a promover as metas da comunidade de ensino e aprendizado
Cada resultado tem uma série de etapas descritas abaixo nas tabelas para os resultados 1 a 3. Enquanto a documentação proposta é enviada para análise, o tutorial de alta prioridade "Matrizes de leitura/gravação" é escrito para envio como uma solicitação de envio como parte do Resultado 2. Durante a revisão do site revisado e o tutorial "Ler/gravar matrizes" atualizado, começarei a criar 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 por elemento em Python.
O terceiro resultado é orientar os alunos da Universidade de Connecticut a criar documentação no repositório numpy-tutorials. Os tutoriais enviados ou documentos de instruções serão notebooks Jupyter que usam NumPy para resolver problemas de engenharia. Vou usar algumas das minhas notas/exemplos do curso para enviar um notebook de exemplo. Aconselho os estudantes a seguirem o layout e a estrutura enquanto criamos o modelo e o esquema de enquadramento. Esse resultado oferece uma experiência genuína para os estudantes comunicarem conceitos e soluções para um público mais amplo. É uma ótima oportunidade para os estudantes se envolverem com a comunidade numpy e aprenderem.
Resultado 1: revise o site. Data de entrega
Resultado 2: revise os tutoriais Data de entrega Revise os tutoriais com classificação 9/21 Separe o conteúdo do tutorial atual em espaços de tutorial e explicação 10/1 Grave a classificação 1: ler/gravar matrizes 10/10 Envie PR ao github para separação e revisão 10/20 Escreva a classificação 2: criação de matriz PR 11/15-brase operações lineares e PR11/15
Classificação proposta de revisões de tutoriais (sujeita a alterações de acordo com mentores/comunidade):
Matrizes de leitura/gravação têm uma página vazia
Criação de matrizes (np.zeros, np.ones, np.block etc.) Não existe: ajudaria os novos usuários a ter as ferramentas comuns de criação/interação de matriz explicada e demonstrada
Operações de álgebra linear e de elemento (+,-,*,/ e +,-@,linalg.solve) Não existe: é especialmente útil para 1. Usuários do Matlab e 2. Pessoas que adotaram álgebra linear (aprendizado de máquina, regressão linear etc.)
Resultado 3: espaço de instruções selecionado Data de entrega Link externo(problema/exemplo)
Exemplo de criação de instruções (candidato: como encontrar frequências naturais das cordas de guitarra 10/20
Criar modelo de instruções para novos colaboradores 10/1 em andamento Modelo de tutorial PR e elaboração de possíveis contribuições: status de pré-aprovação/estude de possíveis contribuições da UF
Significância esperada
Esta proposta do Google Summer of Docs criará a documentação numpy , preencherá os tutoriais ausentes no site e obterá colaboradores para a documentação. Como professor de engenharia mecânica, pretendo segmentar a documentação de forma que os alunos consigam navegar pelos documentos e encontrar facilmente tutoriais introdutórios em vez de guias práticos. A documentação segmentada (tutorial, instruções, referência e explicação) dará aos colaboradores em potencial exemplos estruturados para criar novos recursos. A documentação proposta se destina a uma experiência de educar e comunicar para usuários novos e experientes. O documento de instruções proposto para os estudantes da Universidade de Connecticut colocará essa ideia de educar e comunicar em prática. Queremos que todos os usuários encontrem espaço para experimentar, aprender e participar da comunidade NumPy.
Referências
- Site NumPy.org acessado em 07/2020.
- Repositório NumPy do GitHub.
- O sistema de documentação. Divio.com acessado em 07/2020.
- Dewey, John. Democracia e Educação. Projeto Gutenberg, agosto de 2015.
- Dewey, John. Missão da Certainty George Allen And Unwin Limited. 06/2005.