Projeto NumPy

Esta página contém os detalhes de um projeto de redação 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 fornece computação baseada em matriz limpa e rápida 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 computação eficiente de matriz [2]. Os usuários do 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 cansativos para um iniciante, como NumPy Basics/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 StackExchange para evitar passar pela documentação do NumPy. Atualmente, há mais de 360 mil conversas do StackExchange que lidam com o NumPy. Imagino que outros usuários tiveram caminhos semelhantes para o sucesso no NumPy. Os elementos básicos das ferramentas educacionais são a comunicação e a 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 deve 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 local que acolhe 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 bem-vindos na comunidade.

O conhecimento que os usuários comunicam é obtido por meio de testes [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 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 suas metas, 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 quantidade enorme de experiências genuínas que podem ser compartilhadas com outros usuários. A educação baseia-se na comunidade e na comunicação. Uma página de documentação organizada facilita a experiência do NumPy para novos usuários. Ele também cria um modelo estruturado para que colaboradores em potencial comuniquem experiências com NumPy.

Existem quatro espaços amplamente agrupados para a documentação de software [3]: espaço de tutoriais, espaços 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 combinam o conteúdo de explicação e de instruções espaçadas no tutorial. O espaço do tutorial deve se concentrar na instrução do usuário e usar etapas fáceis de repetir para dar ideias. O espaço de instruções fornece mais procedimentos orientados a metas que os usuários podem aplicar em aplicações do mundo real. O espaço de explicação fornece informações detalhadas em sequências de documentos detalhadas em cada função. O tutorial atual e os espaços de instruções não estão delineados claramente e às vezes entram no espaço de explicação e referência. Há um excelente tutorial para o "Absolute Beginner" e uma ótima referência para usuários do Matlab criarem código NumPy no "Numpy for Matlab users". 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 abrange muitos tópicos necessários, mas não distingue claramente entre tutoriais, instruções, explicações e espaços de referência. o que causa confusão para possíveis colaboradores. Novos usuários podem ficar sobrecarregados com a explicação e o material de referência na seção do tutorial, e os colaboradores em potencial têm dificuldades para contribuir. Proponho um layout mais acessível para iniciantes e possíveis colaboradores com um fluxo lógico na documentação e o gerenciamento de solicitações de envio para documentos de instruções fornecidos pelos usuários por novos colaboradores. Meu objetivo a longo prazo é construir a comunidade de documentação para que aprender 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 visitantes e possíveis colaboradores.

Justificativa

Esta proposta do Google Summer of Docs é importante para meus objetivos pedagógicos e de carreira. Eu uso NumPy e SciPy em todos os meus cursos. A documentação atual é difícil para meus estudantes navegarem. Quero usar minha experiência ao ensinar programação a pessoas que não são de Ciências da Computação para ajudar a organizar, editar e preencher as lacunas dos tutoriais atuais. Depois, posso usar a documentação como um livro didático e material de referência para meus cursos. Criei dezenas de tutoriais, exercícios e exemplos usando Python e . Quero converter parte deste material em tutoriais e instruções. Mais de 800 alunos usaram o NumPy (como parte da pilha Scipy), e vários deles estão interessados em se tornarem colaboradores com a documentação no segundo semestre. Trabalho como professor de Engenharia Mecânica da Universidade de Connecticut há 4 anos e ensinei mais de 30 horas de créditos em cursos.

Objetivos específicos

Tenho três objetivos específicos para essa proposta do Google Summer of Docs: 1. Organize 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. 3. Crie materiais de instruções 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 acolhedora a novos usuários e fornecer estrutura para possíveis colaboradores. O objetivo também ajuda a promover o objetivo de longo prazo de continuar a expandir a comunidade de documentação NumPy. Resultados esperados

Eu tenho três resultados esperados, como: 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 sobre: leitura e gravação de matrizes, criação de matrizes (np.zeros, np.ones, np.block etc.), e operações de álgebra linear e de elemento em NumPy e 3. um espaço de instruções selecionado.

Esses resultados esperados ajudarão os novos usuários a avançar pelos documentos, fornecer aos possíveis colaboradores da documentação estilos e formatos claros, 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 aprendizado.

Novos colaboradores de documentação podem contribuir com pequenos casos de uso para milhões de usuários sem construir toda a documentação do Sphinx. Queremos continuar a construir nossa comunidade de ensino e aprendizado. Esta documentação proposta imita 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 no software.

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 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 da documentação proposta é mostrada abaixo.

Documentação proposta:

i.Tutorials:

  • Conceitos básicos absolutos para iniciantes (remover instalação, a importação/exportação do pandas pode ser substituída por numpy.loadtxt?)
  • link para "What is numpy"
  • link para instruções básicas de instalação aqui
  • Tutorial de início rápido (para acompanhar o tutorial do Python)
  • Como trabalhar com matrizes numpy
  • criação de matrizes (np.zeros, np.ones, np.block, etc.) (gravar: prioridade média-baixa)
  • operações com elementos (+,-,*,/) e operações de álgebra lineares (+,-,@, linalg.solve) (prioridade write:med)
  • Ler e gravar dados usando numpy (gravação: alta prioridade)
  • Indexação

ii. Instruções:

  • Álgebra linear em matrizes n-dimensionais (adoraria editar os títulos e as descrições, talvez alterar o título para “Processamento de imagens com álgebra linear 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)

Após a conclusão da 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 lineares (+,-,@, linalg.solve) e leitura e gravação de dados usando numpy (prioridade alta).
  • Orientou documentos de "como fazer" 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 dos Resultados 1 a 3. Enquanto a documentação proposta é enviada para análise, o tutorial de alta prioridade "Ler/gravar matrizes" será 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 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ções 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 é aconselhar 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. Usarei algumas das minhas notas/exemplos do curso para enviar um caderno de exemplo. Eu aconselho os estudantes a seguir o layout e a estrutura enquanto criamos um modelo e 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: revisão da data de entrega do site Repositório de bifurcação e criação de documentos com o Sphinx 21/9 Crie uma página da Web com quatro espaços definidos e vinculados em 1/10 Mova tutoriais atuais para espaços apropriados e documentos de criação 10/10 Envie RP ao github com alterações propostas 11/11 Responda a comentários/sugestões e revise o RP em andamento com o Resultado 13 Site

Resultado 2: revise os tutoriais. Data de entrega Analise os tutoriais, classificação da revisão 9/21 Separe o conteúdo do tutorial atual em espaços de tutorial e explicação 10/1 Classificação de gravação 1: matriz de leitura/gravação 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 PR10

Classificação proposta de revisões de tutoriais (sujeita a alterações de acordo com mentores/comunidades):

  1. Página vazia em matrizes de leitura/gravação

  2. 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 matrizes explicadas e demonstradas

  3. Operações de álgebra linear e por elemento (+,-,*, e +,-@,linalg.solve) Não existe: isso é especialmente útil para 1. Usuários do Matlab e 2. Pessoas que adotam álgebra linear (machine learning, regressão linear etc.)

Resultado 3: espaço de instruções selecionado, data de entrega Link externo (problema/exemplo) Criar exemplo de instruções (candidato: como encontrar frequências naturais de cordas de violão 10/20
Crie o modelo de instruções para novos colaboradores 10/1 em andamento Modelo de tutorial RP possíveis contribuições Trabalhe com outros colaboradores para criar notebooks de instruções (candidato: como encontrar frequências naturais das cordas de violão 10/20)
Crie o modelo de instruções para novos colaboradores 10/1 em andamento Modelo de tutorial e possíveis contribuições Trabalhe com outros colaboradores para criar cadernos de instruções com membros aprovados e outras inscrições de estudo da UConn 7

Significância esperada

Esta proposta do Google Summer of Docs produzirá a documentação numpy, preencherá os tutoriais que faltam no site e obterá colaboradores para a documentação. Como professor de engenharia mecânica, pretendo segmentar a documentação de modo que meus alunos possam 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á a possíveis colaboradores exemplos estruturados de como criar novos recursos. A documentação proposta serve para dar e receber por meio da experiência de educar e comunicar para usuários novos e experientes. O documento de instruções proposto para os alunos da Universidade de Connecticut colocará em prática essa ideia de educar e comunicar. Queremos que todos os usuários encontrem espaço para experimentar, aprender e participar da comunidade NumPy.

Referências

  1. Site NumPy.org acessado em 07/2020.
  2. NumPy no GitHub.
  3. O sistema de documentação. Divio.com acessado em 07/2020.
  4. Dewey, John. Democracia e Educação. Projeto Gutenberg, agosto de 2015.
  5. Dewey, John. Em Busca da Certeza George Allen And Unwin Limited. 06/2005.