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:
- CERN-HSF
- Redator técnico:
- João
- Nome do projeto:
- CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials
- Duração do projeto:
- De longa duração (5 meses)
Project description
CERN-HSF - ROOT Documentation for General Audience Adoption, Dynamic Python Bindings, and Tutorials Mentor: Olivier Couet, Axel Naumann
Resumo: A documentação é essencial para uma adoção bem-sucedida e eficiente de software pelos usuários. Uma documentação clara, precisa e abrangente facilita a proficiência dos usuários com o software à medida que eles se esforçam para alcançar as metas. Nesse sentido, exemplos e tutoriais explícitos servem como ferramentas poderosas para que os usuários aprendam rapidamente.
À medida que examinamos o uso de ROOT por físicos, pesquisadores e desenvolvedores no espaço de análise de dados e visualização da física, há um reconhecimento dos benefícios de uma documentação fácil de usar e atualizada. Em particular, devido à amplitude do código-fonte e ao crescimento dele, o sistema de documentação pode se beneficiar da evolução paralela para permitir que os usuários maximizem tudo o que o ROOT tem a oferecer.
Resumo e análise da documentação atual Atualmente, a documentação do usuário oferece um guia que permite que físicos adotem o ROOT com mais facilidade em relação ao público em geral. Além disso, em determinados tópicos, como Vinculações dinâmicas de Python, é possível fazer melhorias para conseguir uma documentação mais abrangente e clara. Da mesma forma, o novo formato de dados RNTuple não tem as especificações detalhadas necessárias. Por fim, a documentação atual não tem tutoriais relacionados ao ROOT 7.
Metodologia: Depois de conversar com Olivier, parecia que, para resolver os problemas mencionados, o foco principal deveria ser identificar as lacunas de conhecimento entre pesquisadores especializados e um público em geral, criando uma documentação para preencher essa lacuna, escrevendo uma documentação mais detalhada de Dynamic Python Bindings, implementando "tutoriais para análise moderna" para ROOT 7 e criando especificações técnicas detalhadas para RNTuple. Além disso, durante esse processo, a documentação pode incorporar notebooks Jupyter para que as ferramentas de aprendizagem tangíveis e interativas possam ajudar os usuários.
Cronograma: Estima-se que os estágios do projeto sejam: Identifique lacunas de conhecimento entre pesquisadores especializados e um público geral (durante a leitura da documentação e do código-fonte atuais) → 1 a 2 semanas Crie e refatore a documentação para preencher essa lacuna → 3 semanas Escreva uma documentação mais detalhada de vinculações dinâmicas de Python → 3 semanas Implemente tutoriais para vinculações dinâmicas de Python → 3 semanas Implementação de tutoriais para vinculações dinâmicas de Python → 3 semanas Implementação de tutoriais para vinculações dinâmicas de Python → 3 semanas concluídas
Entregas e diretrizes para o sucesso: documentação unificada para o usuário sem lacunas Documentação do usuário totalmente atualizada para refletir os recursos mais recentes, ou seja, novas classes derivadas Tutoriais usando notebooks do Jupyter