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:
- 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 atual para que ela seja facilmente acessada por usuários com diferentes necessidades. É óbvio que um pesquisador provavelmente está mais interessado em atributos avançados e sutis, enquanto um usuário sem experiência prévia gosta de guias e diagramas passo a passo.
Estou interessado em realizar este projeto por motivos pessoais e profissionais: em primeiro lugar, gostaria de contribuir significativamente para a SciPy porque minha própria pesquisa se beneficiou muito com isso e, em segundo lugar, encontro documentação insuficiente (ou com falta) com muita frequência em outros softwares e sempre me pergunto em quanto mais rápido os usuários poderiam aprender a usar o código se tivessem recebido um guia completo.
Metas:
Meu objetivo é melhorar a documentação SciPy existente em termos gráficos e de conteúdo. O recurso mais importante da minha abordagem para esse problema é a implantação e a análise da pesquisa com usuários, 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 a 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 com 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 ao lado de matrizes bidimensionais), frases complicadas que devem ser reescritas ou falta de ordem alfabética em determinadas subpáginas. A segunda fase se concentrará 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, desejo alcançar uma documentação satisfatória sob medida para diferentes tipos de usuários. Além disso, tentarei tornar os tutoriais mais consistentes, tanto linguísticamente quanto estruturalmente. Por último, mas não menos importante, meu objetivo é escrever novos tutoriais baseados nas necessidades atuais da comunidade.
Pesquisa de usuário:
Em relação à pesquisa com usuários, proponho o uso do 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, parece que o Formulários Google é, pelo menos por enquanto, a melhor ferramenta sem custo financeiro para realizar pesquisas. De forma menos séria, seria um bom gesto usar um produto do Google em uma iniciativa do Google.
Criei uma pesquisa preliminar com exemplos de perguntas (pode ser acessada em https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Um número razoável de perguntas na versão final deve ser entre dez e quinze. Para obter resultados concretos, sugiro que façamos predominantemente perguntas 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 sofrem com alta dispersão). Deve haver no máximo duas perguntas abertas. Caso contrário, os resultados ficarão muito dispersos e não serão úteis. Acredito 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 um software estatístico. Supondo que o número de respostas seja realmente muito alto, a análise das perguntas abertas pode ser um pouco demorada, mas presumo que não seja sobrecarregado. Afinal, é pouco provável que um usuário comum escreva um ensaio sobre o estado de uma documentação. Na pior das hipóteses, algumas respostas podem ser simplesmente armazenadas para análises futuras.
Guias gráficos:
Minha visão dos guias gráficos (destinados a servir como ferramentas de navegação) baseia-se em uma premissa popular de que (a maioria) os humanos são melhores em processar estruturas visuais diretas em vez de informações puramente baseadas em texto. Além disso, um diagrama temático com linhas conectando tópicos de interesse semelhantes é, sem dúvida, um bem muito valioso para usuários menos experientes (e não apenas).
Quanto aos detalhes da implementação, sugiro usar o pacote TikZ. Em primeiro lugar, é uma ferramenta poderosa e não parece correr o risco de ser descontinuada em breve. Ele também oferece resultados de alta qualidade, tem uma documentação realmente sólida e é um tópico frequente no TeX StackExchange 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 representar 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 uns dos outros. A estrutura, a paleta de cores e as formas são, quase sempre, invariantes. Portanto, a remodelação e a personalização posteriores não serão um problema.
Confira a versão completa da proposta, disponível na pasta compartilhada do GSoD.