Esta página foi traduzida pela API Cloud Translation.

Projeto Matplotlib

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:: Matplotlib
Redator técnico:: jeromev
Nome do projeto:: Como desenvolver caminhos de entrada do Matplotlib
Duração do projeto:: Duração padrão (3 meses)

Project description

Introdução

A sugestão de projeto da Matplotlib para a temporada de Documentos Google deste ano envolve a criação de conteúdo que ajuda a introduzir o Matplotlib a novos usuários. Para o desenvolvimento de caminhos de entrada do Matplotlib, proponho uma abordagem alternativa à atual. Sou um novo escritor técnico do setor, mas minha formação é em áreas adjacentes à educação e à educação. A escrita técnica e a educação têm fortes paralelos com foco na produção de conteúdo que gera empatia e permite que os usuários realizem tarefas com os recursos fornecidos.

Nesse contexto, a documentação do Matplotlib se beneficiaria com uma melhoria no desenvolvimento de empatia por novos usuários. Atualmente, grande parte do material consiste em dados aleatórios e visuais não rotulados. Eles são excelentes para exibir rapidamente os recursos visuais e os recursos do Matplotlib. No entanto, para o caso de uso de Matplotlib, é um desafio atravessar a transformação de dados para recursos visuais.

Um contexto, em uma abordagem expositiva, é uma solução para esse obstáculo. Ao escrever um procedimento da perspectiva de um exemplo do mundo real, demonstramos uma compreensão do ambiente no qual um usuário trabalha. Isso melhora a relação entre a documentação e o usuário em termos de alcançar uma meta ou expectativa de realizar uma tarefa.

Um usuário tem uma finalidade derivada consistente. Por exemplo, um cientista de dados de uma empresa de calçados precisa apresentar os dados do cliente a uma equipe para ilustrar as tendências de compras ao longo do tempo. Nessa situação, o usuário precisa aprender a navegar pelo Matplotlib e aproveitar as ferramentas da biblioteca para concluir a tarefa em questão.

Com mais contexto para embasar a documentação, um novo usuário pode se identificar mais com o tema. A finalidade derivada do usuário é paralela à documentação. Espero trabalhar em direção à visão que o desenvolvedor-chefe Tom Caswell discutiu em uma entrevista em 2017 de "ter alguém que possa realmente escrever e ter empatia pelos usuários, passar e basicamente escrever um livro 'Introdução ao Matplotlib' de 200 páginas e ter essa ser a entrada principal para os documentos".

Abordagem alternativa da escrita expositiva

A documentação atual demonstra os recursos do Matplotlib, ou seja, as coisas que um usuário pode fazer com a biblioteca. Por exemplo, um tutorial geralmente segue o padrão que não envolve uma explicação do método subjacente.

{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}

Geralmente, com documentação e suporte de programação, recomenda-se que um usuário execute o código por conta própria para entender o que acontece. Embora uma mentalidade de programação melhore a compreensão de um usuário sobre um tópico, a curva de aprendizado das transformações tem pouco conteúdo de apoio. Pode ser um desafio e tanto, já que a documentação é limitada.

A apresentação de diagramas, imagens ou outros recursos visuais ajuda a criar novas oportunidades de aprendizado. A estrutura abaixo também serviria bem como um modelo para novos conteúdos. Além disso, adicionar imagens ou gráficos não textuais pode se beneficiar de recursos como frases de destaque e marcas de treinamento. Há momentos em que é mais difícil navegar pelas imagens sem indicações de como ou onde o código é transformado na saída executada. Acho que falta um elemento visual forte que poderia promover uma maior compreensão dos temas.

{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}

Há um enorme potencial nessa abordagem alternativa de usar a escrita expositiva para documentação. Ao ver uma variedade de conceitos de transformações, os usuários seriam capazes de identificar melhor as estratégias subjacentes do desenvolvimento de visualizações de dados. Esse conhecimento pode ajudar os usuários a inovar e aproveitar os recursos apresentados por exemplos baseados em casos de uso realistas.

À medida que Matplotlib cresce em popularidade, a consistência na facilidade de uso e a acessibilidade são prova da reputação da biblioteca. Essas características servem para demonstrar padrões e estratégias comuns que podem surgir não apenas no código, mas também na documentação. Se o Matplotlib for simples e padrão para os usuários programarem, como evidente no uso crescente e na expansão de recursos, ele também pode ser dessa forma para a documentação técnica.

Quando os usuários encontram problemas, é comum usar a pesquisa para resolvê-los. Em vez de confiar na pesquisa como o método principal de navegação, pode ser mais impactante fazer com que os usuários criem seu próprio currículo dentro da documentação. Nesse sentido, um usuário procura uma solução para seu problema e, quando encontrar outro problema ou quiser informações adicionais, ele fará uso de links incorporados e completos.

Isso envolveria uma arquitetura ascendente no sistema organizacional. Para cada tópico dentro do Matplotlib, uma rica rede de links para afinidades de assuntos e tópicos informativos ajudaria a criar uma rede robusta. Em toda essa rede, é mais provável que o usuário continue usando a documentação à medida que navega pelo tópico e explora cada vez mais informações relacionadas a ele.

Obstáculos

Há sempre desafios em um projeto tão abrangente e detalhado como esse. Como redator técnico mais novo no setor, tenho experiência limitada no uso de Sphinx e ReST para escrever documentação. Também sou iniciante em Matplotlib e em Git. Levará tempo para lidar com esses quatro sistemas e se familiarizar com o uso deles para colaboração e pesquisa. Vou precisar delegar tempo durante a fase de ligação com a comunidade (e antes) para construir a base necessária para os caminhos de nível básico. Durante esse período, se tiver problemas com conceitos e princípios básicos, precisarei entrar em contato com a comunidade para receber mais ajuda.

Coordenar esforços colaborativos entre fusos horários e plataformas on-line também exigirá ajustes. As pessoas de todo o setor usam vários meios de comunicação, então é uma questão de garantir que sou acessível e acessível em todos os meios. Serei transparente ao priorizar as diferentes expectativas. Eu estou apenas começando a assumir um trabalho como este no setor, mas estou focado em me manter responsável e em estar aberto a feedback e críticas. Sinto que essas qualidades são valiosas em qualquer área.

Além disso, aumentar os testes de usabilidade é uma seção da documentação que beneficiaria os caminhos de entrada do Matplotlib. A realização de pesquisas de usabilidade em relação ao conteúdo serve para fornecer um perfil de usuário, ou seja, personas. Informações como a experiência do usuário, o setor e o histórico de solução de problemas são valiosas. Essas peças ajudam a formar a linguagem por trás do procedimento. Quando a escrita encontra os leitores no nível deles, o conteúdo amadurece além de ser apenas instrutivo.

Muitas vezes, é difícil criar uma prática contínua de testes de usabilidade. É muito comum ter tido uma única instância de teste, se realizado, durante o desenvolvimento de conteúdo. Testes de usabilidade regulares ajudam a direcionar a narrativa do conteúdo. Seria minha esperança de configurar um cronograma ou ter testes de usabilidade recorrentes com a comunidade Matplotlib.

Conclusão

Tenho um pouco de experiência com Python e Matplotlib em meu tempo livre. Aprendi coisas sozinha nos últimos meses com o apoio da documentação atual e minha própria curiosidade. Eu tive vários vídeos e mentores nesse período também. Ainda tenho muito o que aprender e mais espaço para melhorar enquanto crio meu próprio currículo de programação no qual tenho interesse.

Depois de ver as ideias que Matplotlib e a comunidade têm para o GSoD, sinto que seria uma excelente experiência de crescimento para melhorar minhas habilidades como redator técnico e ter a chance de aprender mais com o pessoal nos bastidores. Eu senti que o projeto Matplotlib é significativo e é algo que eu gosto na ideologia.

Para trabalhar em uma reformulação do guia de uso, meu objetivo como redator técnico é ajudar os usuários a realizar as tarefas que eles querem sem ficar sobrecarregados com os recursos disponíveis. Acredito que a melhor documentação continuaria a crescer e se adaptar aos usuários, permitindo que qualquer usuário navegue até as próprias soluções.