Esta página foi traduzida pela API Cloud Translation.

Projeto Matplotlib

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:: Matplotlib
Redator técnico:: jeromev
Nome do projeto:: Como desenvolver caminhos de entrada de 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 deste ano do Google Docs envolve a criação de conteúdo que ajuda a introduzir o Matplotlib para novos usuários. Para desenvolver caminhos de entrada de Matplotlib, proponho uma abordagem alternativa à da documentação atual. Sou um novo escritor técnico do setor, mas tenho experiência em áreas adjacentes à educação e educação. A escrita técnica e a educação têm fortes paralelos que focam 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 melhorias no desenvolvimento de empatia com novos usuários. Atualmente, grande parte do material consiste em dados aleatórios e recursos 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 alguém novo a usar o Matplotlib, é desafiador passar pela transformação de dados para recursos visuais.

Em uma abordagem expositiva, um contexto é 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 em que um usuário trabalha. Isso melhora o relacionamento entre a documentação e o usuário em termos de alcançar um objetivo ou expectativa de realizar uma tarefa.

Um usuário tem um objetivo derivado 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 dar suporte à documentação, um novo usuário pode ser mais capaz de se identificar com o tópico. A finalidade derivada do usuário é paralela à documentação. Espero trabalhar com a visão que o desenvolvedor-chefe Tom Caswell discutiu em uma entrevista em 2017 como "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 principal entrada para os documentos".

Abordagem alternativa da escrita expositiva

A documentação atual demonstra os recursos do Matplotlib, ou seja, o que o 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}

Muitas vezes, com a documentação e o suporte de programação, recomenda-se que o 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 tema, a curva de aprendizado de transformações tem pouco conteúdo de apoio. Pode ser um desafio esmagador porque a documentação é limitada.

Fornecer novos diagramas, imagens ou outros recursos visuais ajuda a criar novas oportunidades de aprendizado. A estrutura abaixo também serviria como modelo para novos conteúdos. Além disso, o objetivo de 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. Acredito 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}

Essa abordagem alternativa tem um potencial enorme de usar a escrita contábil para documentação. Com vários conceitos de transformações, os usuários conseguiriam 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 o Matplotlib cresce em popularidade, consistência na facilidade de uso e acessibilidade são uma 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 direto e padrão para os usuários programarem, como evidente no uso crescente e na expansão de recursos, também pode ser dessa maneira para a documentação técnica.

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

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

Obstáculos

Sempre há desafios em um projeto tão abrangente e detalhado como esse. Como redator técnico mais novo no setor, tenho pouca experiência usando Sphinx e ReST para escrever documentação. Também sou iniciante no Matplotlib e também no Git. Lidar com esses quatro sistemas e se familiarizar com o uso deles para colaboração e pesquisa levará tempo. Vou precisar delegar tempo durante a fase de conexã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 eu tiver problemas com conceitos e fundamentos, precisarei entrar em contato com a comunidade para receber mais suporte.

Coordenar esforços colaborativos entre fusos horários e plataformas on-line também precisará de alguns ajustes. 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 diversas expectativas. Embora eu esteja apenas começando a assumir um trabalho como esse no setor, estou investido em me responsabilizar e estou 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 tem a finalidade de 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 o leitor em seu nível, o conteúdo amadurece além de atuar apenas como instrutivo.

Muitas vezes, as grandes dificuldades são a criação de uma prática contínua de testes de usabilidade. É muito comum ter uma única instância de teste, se feito, durante o desenvolvimento de conteúdo. Testes de usabilidade regulares ajudam a orientar a narrativa do conteúdo. Seria minha esperança de organizar um cronograma ou ter testes de usabilidade recorrentes com a comunidade Matplotlib.

Conclusão

Tenho um pouco de experiência com Python e Matplotlib no meu tempo livre. O que aprendi sozinho nos últimos meses foi com o apoio da documentação atual e minha própria curiosidade. Tive muitos vídeos e mentores nesse período. Ainda tenho muito o que aprender e ainda 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 o Matplotlib e a comunidade têm para o GSoD, sinto que seria uma experiência de crescimento excelente 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 adoro em 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 desejam 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 para suas próprias soluções.