Esta página contém os detalhes de um projeto de escrita técnica aceito para o Temporada dos Documentos 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 (três meses)
Project description
Introdução
A sugestão de projeto do Matplotlib para a Temporada de documentos do Google deste ano envolve a criação de conteúdo que ajuda a apresentar o Matplotlib a novos usuários. Para desenvolver caminhos de entrada do Matplotlib, proponho uma abordagem alternativa à documentação atual. Sou um redator técnico novo no setor, mas tenho experiência em educação e áreas relacionadas. A escrita técnica e a educação têm fortes paralelos que se concentram 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 para criar empatia com novos usuários. No momento, grande parte do material consiste em dados aleatórios e recursos visuais não rotulados. Eles são excelentes para mostrar rapidamente os recursos visuais e de Matplotlib. No entanto, para o caso de uso de alguém que não conhece a Matplotlib, é difícil transformar dados em recursos visuais.
Um contexto em uma abordagem expositiva é uma solução para esse obstáculo. Ao escrever um procedimento usando um exemplo do mundo real, demonstramos que entendemos o ambiente em que o 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 dados de clientes a uma equipe para ilustrar as tendências de compras ao longo do tempo. Nessa situação, o usuário precisa aprender a navegar no Matplotlib e aproveitar as ferramentas da biblioteca para concluir a tarefa em questão.
Com mais contexto para apoiar a documentação, um novo usuário pode se identificar melhor 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, como “tendo alguém que possa realmente escrever e ter empatia pelos usuários, analisar e escrever um livro ‘Introdução ao Matplotlib’ de 200 páginas e fazer com que essa seja a entrada principal dos documentos”.
Abordagem alternativa de escrita expositiva
A documentação atual demonstra os recursos do Matplotlib, ou seja, o 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}
Muitas vezes, com a documentação e o suporte de programação, é recomendável 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 do usuário sobre o assunto, a curva de aprendizado para transformações tem pouco conteúdo de apoio. Isso pode ser um desafio, já que a documentação é limitada.
O fornecimento de diagramas, imagens ou outros recursos visuais adicionais ajuda a criar novas oportunidades de aprendizagem. A estrutura abaixo também serve como 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 do coach. Às vezes, é mais difícil navegar por 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 ajudar a entender melhor os tópicos.
{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. Com uma variedade de conceitos de transformações, os usuários poderão identificar melhor as estratégias subjacentes de desenvolvimento de visualizações de dados. Esse conhecimento pode ajudar os usuários a inovar e aproveitar os recursos apresentados por exemplos com base em casos de uso realistas.
À medida que a popularidade do Matplotlib cresce, a consistência na facilidade de uso e a acessibilidade são um testemunho da reputação da biblioteca. Essas características servem para demonstrar padrões e estratégias comuns que podem aparecer não apenas no código, mas também na documentação. Se o Matplotlib for simples e padrão para os usuários programar, como evidenciado pelo uso crescente e pela expansão dos recursos, ele também poderá ser assim 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 principal método de navegação, pode ser mais impactante fazer com que os usuários criem o próprio currículo na documentação. Nesse sentido, um usuário procura uma solução para seu problema e, quando encontra outro problema ou quer mais informações, usa links incorporados e completos.
Isso envolveria uma arquitetura bottom-up no sistema organizacional. Para cada tópico no Matplotlib, uma rede rica de links para afinidades de assunto, bem como tópicos informativos, ajudaria a criar uma rede robusta. Nessa rede, é mais provável que o usuário continue usando a documentação ao navegar até o tópico e explorar cada vez mais informações relacionadas a ele.
Obstáculos
Sempre há desafios em um projeto tão abrangente e detalhado quanto este. Como redator técnico mais recente do setor, tenho experiência limitada no uso do Sphinx e do ReST para escrever documentação. Também sou iniciante em Matplotlib e Git. Lidar com esses quatro sistemas e se sentir confortável para usá-los para colaboração e pesquisa levará tempo. Vou precisar delegar tempo durante a fase de integração da comunidade e antes disso para criar a base necessária para os caminhos de nível básico. Durante esse período, se eu tiver problemas com conceitos e fundamentos, vou precisar entrar em contato com a comunidade para receber mais suporte.
A coordenação de esforços colaborativos entre fusos horários e plataformas on-line também vai exigir alguns ajustes. Há várias formas de comunicação que as pessoas em todo o setor usam. Por isso, é importante garantir que eu seja acessível e acessível em todos os meios. Vou priorizar as expectativas diferentes de forma transparente. Embora eu esteja apenas começando a aceitar trabalhos como esse na indústria, estou comprometida em me responsabilizar e estar aberta 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 acredito que beneficiaria os caminhos de entrada do Matplotlib. A realização de pesquisas de usabilidade relacionadas 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 partes ajudam a formar a linguagem por trás do procedimento. Quando o texto atende ao nível dos leitores, o conteúdo amadurece e deixa de ser apenas instrutivo.
Muitas vezes, as grandes dificuldades estão relacionadas à criação de uma prática contínua de testes de usabilidade. É muito comum ter uma única instância de teste, se houver, durante o desenvolvimento do conteúdo. Testes de usabilidade regulares ajudam a impulsionar a narrativa do conteúdo. Gostaria de configurar uma programação ou ter testes de usabilidade recorrentes com a comunidade do Matplotlib.
Conclusão
No meu tempo livre, tenho um pouco de experiência com Python e Matplotlib. O que aprendi nos últimos meses foi o apoio da documentação atual e a minha própria curiosidade. Eu também tive alguns mentores e assisti alguns vídeos nesse período. Ainda tenho muito a aprender e ainda mais espaço para melhorar à medida que crio meu próprio currículo de programação em que tenho interesse.
Depois de ver as ideias que o Matplotlib e a comunidade têm para o GSoD, acho que seria uma excelente experiência de crescimento para melhorar minhas habilidades como redator técnico e ter a chance de aprender mais com as pessoas por trás dos bastidores. Sinto que este projeto do Matplotlib é significativo e algo que me apaixona pela ideologia.
Para trabalhar na revisão do guia de uso, meu objetivo como redator técnico é ajudar os usuários a realizar as tarefas que eles querem sem se sobrecarregar com os recursos disponíveis. Acredito que a melhor documentação vai continuar crescendo e se adaptando aos usuários, permitindo que eles encontrem as próprias soluções.