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:
- A linguagem Julia
- Redator técnico:
- mkg33
- Nome do projeto:
- A documentação unificada do machine learning científico
- Duração do projeto:
- De longa duração (5 meses)
Project description
Gostaria de trabalhar na unificação da organização SciML porque há muito espaço para melhoria nessa área, e a conclusão deste projeto, sem dúvida, trará benefícios imediatos para os programadores da Julia e para os colaboradores e mantenedores ativos da SciML. Os pacotes espalhados pela SciML oferecem algumas ferramentas realmente úteis, mas há sempre o perigo de que elas possam passar despercebidas (especialmente para iniciantes) simplesmente porque o usuário não conseguiu descobrir o pacote e aplicá-lo ao problema em questão.
Isso é frustrante, já que o objetivo principal dos pacotes é atingir um amplo público de programadores (iniciantes e especialistas). Para evitar a situação descrita acima, proponho uma revisão completa da "página inicial" da documentação da SciML e a criação de um tipo de hub que os usuários possam usar para procurar 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 existente de todos os pacotes individuais precisa ser revisada em relação aos problemas de estilo mais básicos (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 precisa se basear nas convenções atuais de Julia e incluir novos inteiros para questões específicas da SciML.
Após a conclusão do guia de estilo, pretendo revisar a documentação atual na segunda fase do projeto. Isso tornará a documentação mais profissional e estável. Já criei várias solicitações de envio que ilustram minha abordagem nessa tarefa. Nesta fase, também pretendo criar (e implementar) um sistema de citação eficiente. A primeira tarefa será atualizar a página de citações desatualizada.
A terceira fase, possivelmente a mais importante, envolverá a criação do roteiro da SciML, que enfatizará a interação entre os pacotes dispersos. Quanto mais forte for a coesão entre dois pacotes (em relação ao problema ou ao próprio código), mais próximos eles aparecerão na lista "veja também". Proponho a criação de duas chaves de recomendação: uma para similaridade de código e outra para similaridade de problemas. Dessa forma, os usuários poderiam identificar outros pacotes potencialmente úteis com muito mais rapidez do que por navegarem pelos respectivos repositórios e documentação. Em vez de listar todas as conexões possíveis entre os pacotes, prefiro focar nas conexões 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 deve ser destacada). Essa abordagem garante que as listas "Consulte também" sejam informativas, sem enumerações exaustivas de combinações de pacotes.