Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
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 (três meses)
Project description
Motivação:
Pretendo trabalhar na refatoração da documentação atual para que ela seja facilmente acessível a usuários com necessidades diferentes. É óbvio que um pesquisador provavelmente está interessado em recursos avançados e sutis, enquanto um usuário sem experiência anterior aprecia guias e diagramas detalhados.
Tenho interesse em continuar este projeto por motivos pessoais e profissionais: em primeiro lugar, gostaria de contribuir significativamente para o SciPy porque minha própria pesquisa se beneficiou muito dele. Em segundo lugar, encontro documentação insuficiente (ou falta dela) com muita frequência em outros softwares e sempre me pergunto se os usuários poderiam aprender a usar o código muito mais rápido (se é que isso acontece) se tivessem recebido um guia completo.
Metas:
Meu objetivo é melhorar a documentação existente do SciPy em termos de conteúdo e gráfico. 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 conduzida on-line que permita que vários usuários expressem suas necessidades em relação à documentação. Acredito que as opiniões deles sejam a fonte de inspiração (como mais podemos criar uma documentação mais fácil de usar?).
Quanto à realização do projeto, a primeira fase envolve o design e a análise da pesquisa de usuários, além de resolver vários problemas de estilo que notei na documentação atual. Por exemplo, falta de consistência (por exemplo, matrizes bidimensionais que ocorrem com matrizes bidimensionais), frases confusas que precisam ser reescritas ou a falta de ordem alfabética em determinadas subpáginas. A segunda fase vai se concentrar na introdução de guias gráficos com hiperlinks para os temas relevantes (com base nos resultados da pesquisa e em outras solicitações da comunidade). No longo prazo, quero ter uma documentação satisfatória adaptada a diferentes tipos de usuários. Além disso, vou tentar tornar os tutoriais mais consistentes tanto linguística quanto estruturalmente. Por último, mas não menos importante, pretendo escrever novos tutoriais com base nas necessidades atuais da comunidade.
Pesquisa com usuários:
Quanto à pesquisa com usuários, proponho o uso dos Formulários Google por vários motivos. Em primeiro lugar, o Google Formulários é sem custo financeiro e oferece funcionalidades ilimitadas (em termos de número de respondentes, perguntas etc.), tem um formato visual atraente, as opções de pesquisa mais úteis (por exemplo, a escala linear personalizável, caixas de seleção e múltipla escolha) e, o mais importante, os resultados podem ser exportados com facilidade 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. Em uma nota menos séria, seria um gesto legal usar um produto do Google em uma iniciativa realizada pelo Google.
Criei uma pesquisa preliminar com exemplos de perguntas (acesse 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 usemos principalmente perguntas de múltipla escolha, uma escala linear e algumas caixas de seleção. A escala linear não deve se parecer com um espectro completo, porque isso causa confusão e os resultados provavelmente sofrerão uma 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. 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 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 será muito difícil. Afinal, é improvável que um usuário comum escreva um ensaio sobre o estado da 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 conhecida 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 que conectam tópicos de interesse semelhantes é, sem dúvida, um recurso altamente valioso (e não apenas) para usuários menos experientes.
Em relação aos detalhes de implementação, proponho usar o pacote TikZ. Em primeiro lugar, é uma ferramenta poderosa e não parece estar em risco de descontinuação em breve. Ele também oferece saída de alta qualidade, tem uma documentação muito sólida e é um tópico frequente no TeX StackExchange e em outros fóruns comuns. O mais importante é que a integração de um arquivo TikZ (mais precisamente, os vários hiperlinks nele) com a documentação HTML não parece causar 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 resolvida facilmente usando, por exemplo, o Overleaf (que facilita a colaboração e oferece uma visualização instantânea) e modelos predefinidos que vou fornecer. Basicamente, os guias gráficos não costumam ser muito diferentes entre si. A estrutura, a paleta de cores e as formas são, mais ou menos, invariáveis, portanto, a remodelagem e a personalização subsequentes não serão um problema.
Consulte a versão completa da proposta, disponível na pasta GSoD compartilhada.