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:
- A linguagem Julia
- Redator técnico:
- mkg33
- Nome do projeto:
- A documentação unificada do Scientific Machine Learning
- Duração do projeto:
- Longa duração (cinco meses)
Project description
Gostaria de trabalhar na unificação da organização SciML, porque há muito espaço para melhorias nessa área, e a conclusão desse projeto sem dúvida vai trazer benefícios imediatos tanto para os programadores de Julia quanto para os colaboradores/mantenedores ativos do SciML. Os pacotes espalhados pelo SciML oferecem ferramentas muito úteis, mas sempre há o perigo de que eles passem despercebidos (especialmente pelos novatos) simplesmente porque o usuário não conseguiu descobrir o pacote e aplicá-lo ao problema em questão.
Isso é bastante frustrante, já que o objetivo principal dos pacotes é alcançar um público amplo de programadores (iniciantes e especialistas). Para evitar a situação descrita acima, proponho revisar a "página inicial" da documentação do SciML e criar uma espécie de hub que os usuários possam usar para navegar por pacotes relacionados e explorar o ecossistema em crescimento. Ele também pode servir como um ponto de referência valioso para usuários mais experientes e permitir que eles trabalhem com mais eficiência.
Em primeiro lugar, a documentação atual de todos os pacotes individuais precisa ser revisada em relação aos problemas mais básicos de estilo (como ortografia, pontuação, gramática etc.). Para garantir a consistência estilística, o SciML precisa ter um guia de estilo concreto, indispensável para fazer mudanças retrospectivas e para referência futura. Seria uma perda de tempo começar do zero. Em vez disso, ele deve se basear nas convenções existentes de Julia e incluir novos resumos para questões específicas da SciML.
Uma vez concluído o guia de estilo, pretendo revisar a documentação atual na segunda fase do projeto. Isso vai deixar a documentação mais profissional e estável. Já criei várias solicitações de envio que ilustram minha abordagem para essa tarefa. Nesta fase, também pretendo criar e implementar um sistema de citações eficiente. A primeira tarefa será atualizar a página de citações desatualizada.
A terceira fase, provavelmente a mais importante, envolve o planejamento do roteiro do SciML, que enfatiza a interação entre os pacotes dispersos. Quanto maior a coesão entre dois pacotes (com relação ao problema ou ao próprio código), mais próximos eles vão aparecer na lista "Ver também". Proponho criar duas chaves de recomendação: uma para a similaridade de código e outra para a similaridade de problema. Dessa forma, os usuários conseguiriam identificar outros pacotes potencialmente úteis com muito mais rapidez do que uma navegação trabalhosa pelos respectivos repositórios e documentações. Em vez de listar todas as conexões possíveis entre os pacotes, prefiro me concentrar nos maiores e tentar apresentar os links com pacotes menores. Esse método também será estendido para atualizar tutoriais em que a conexão com outro pacote precisa ser indicada. Essa abordagem garante que as listas "ver também" sejam informativas sem ser enumerações exaustivas de combinações de pacotes.