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:
- SciPy
- Redator técnico:
- mkg33
- Nome do projeto:
- Documentação orientada ao usuário e reestruturação completa
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Motivação:
Pretendo trabalhar na refatoração da documentação existente para que ela seja facilmente acessada por usuários com diferentes necessidades. É óbvio que um pesquisador provavelmente está interessado em recursos avançados e sutis, enquanto um usuário sem experiência prévia gosta de guias e diagramas passo a passo.
Tenho interesse em buscar este projeto por motivos pessoais e profissionais: primeiro, gostaria de contribuir significativamente para a SciPy porque minha própria pesquisa se beneficiou com ele e, em segundo lugar, encontro com muita frequência (ou falta) documentação insuficiente em outros softwares e sempre me pergunto em quanto mais rápido (se isso for tudo!) os usuários poderiam aprender a usar o código se tivessem recebido um guia completo.
Metas:
Meu objetivo é melhorar a documentação do SciPy em termos gráficos e de conteúdo. O elemento mais importante da minha abordagem para esse problema é a implantação e a análise da pesquisa do usuário, ou seja, uma pesquisa concisa realizada on-line, permitindo que vários usuários expressem suas necessidades em relação à documentação. Acredito fortemente que as opiniões deles devem ser uma fonte de inspiração (de que outra forma podemos criar uma documentação mais fácil de usar?).
Quanto à realização do projeto em si, a primeira fase envolve projetar e analisar a pesquisa de usuários, bem como resolver vários problemas estilísticos que notei na documentação atual. Por exemplo, falta de consistência (como matrizes bidimensionais que ocorrem junto com matrizes bidimensionais), sentenças complicadas que precisam ser reescritas ou falta de ordem alfabética em algumas subpáginas. A segunda fase será focada na introdução de guias gráficos contendo hiperlinks para os tópicos relevantes (com base nos resultados da pesquisa e em outras solicitações da comunidade). A longo prazo, pretendo alcançar uma documentação satisfatória personalizada para diferentes tipos de usuários. Além disso, tentarei tornar os tutoriais mais consistentes em termos linguísticos e estruturais. Por último, mas não menos importante, meu objetivo é escrever novos tutoriais (com base nas necessidades atuais da comunidade).
Pesquisa de usuário:
Em relação à pesquisa dos usuários, sugiro usar o Formulários Google por várias razões. Em primeiro lugar, o Formulários Google é sem custo financeiro e oferece funcionalidade ilimitada (em termos de número de participantes, perguntas etc.), tem um formato visual atraente, as opções de pesquisa mais úteis (por exemplo, escala linear personalizável, caixas de seleção e múltipla escolha) e, o mais importante, os resultados podem ser facilmente exportados para fins de análise estatística. Com base em pesquisas on-line, o Formulários Google parece ser, pelo menos por enquanto, a melhor ferramenta sem custo financeiro para a realização de pesquisas. De forma menos séria, seria um bom gesto usar um produto do Google em uma iniciativa conduzida pelo Google.
Criei uma pesquisa preliminar com exemplos de perguntas (acesse https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Um número razoável de perguntas na versão final deve ter entre 10 e 15. Para obter resultados concretos, sugiro que usemos questões de múltipla escolha, uma escala linear e algumas caixas de seleção. No entanto, a escala linear não deve se assemelhar a um espectro completo (isso apenas causa confusão e os resultados provavelmente sofrerão alta dispersão). Deve haver no máximo duas perguntas abertas. Caso contrário, os resultados serão muito dispersos e não serão úteis. Reconheço que mesmo um número muito alto de respostas não seria problemático, porque os dados podem ser facilmente exportados e analisados automaticamente com software estatístico. Supondo que o número de respostas seja, de fato, muito alto, a análise das perguntas abertas pode ser um pouco demorada, mas presumo que não seja sobrecarregada. Afinal, é pouco provável que um usuário comum escreva um artigo sobre o estado de uma documentação. Na pior das hipóteses, algumas respostas podem ser simplesmente armazenadas para análise futura.
Guias gráficos:
Minha visão dos guias gráficos (destinados a servir como ferramentas de navegação) se baseia na premissa popular de que (a maioria) dos humanos é melhor em processar estruturas visuais diretas em vez de informações baseadas apenas em texto. Além disso, um diagrama temático com linhas que conectam tópicos de interesse semelhantes é, sem dúvida, um recurso altamente valioso para usuários menos experientes (e não apenas).
Em relação aos detalhes de implementação, sugiro usar o pacote TikZ. Em primeiro lugar, é uma ferramenta poderosa e não parece correr o risco de ser descontinuado em breve. Ele também oferece resultados de alta qualidade, tem uma documentação muito sólida e é um assunto frequente no TeX Stack Exchange e em outros fóruns convencionais. Mais importante ainda, a integração de um arquivo TikZ (mais precisamente, os vários hiperlinks contidos nele) com a documentação HTML não parece apresentar problemas significativos devido à existência de vários pacotes e correções para incorporar uma imagem TikZ em HTML (por exemplo, TeX4ht).
A questão da manutenção futura dos guias no SciPy pode ser facilmente resolvida usando, digamos, o Overleaf (facilita a colaboração e oferece uma visualização instantânea) e modelos predefinidos que vou fornecer. Basicamente, os guias gráficos provavelmente não serão muito diferentes entre si. A estrutura, a paleta de cores e as formas são invariantes. Portanto, a remodelação subsequente e a personalização adicional não serão um problema.
Consulte a versão completa da proposta, disponível na pasta compartilhada do GSoD.