Projeto DIPY

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:

DIPY

Redator técnico:

Areesha Tariq

Nome do projeto:

Reestruturação de alto nível e foco no usuário final

Duração do projeto:

Duração padrão (três meses)

Project description

Sou engenheiro de software e tenho experiência em redação técnica. Tenho mais de quatro anos de experiência na criação de documentação de software, guias do usuário, manuais e descrições de projetos de alta qualidade. Moro em Islamabad, Paquistão (Fuso horário: UTC + 5). Atualmente, estou trabalhando como estagiário na Outreachy, o que vai continuar até 18 de agosto. Participei da Google Season of Docs como redatora técnica na organização OpenELIS Global. A documentação original estava em francês, era limitada e desatualizada. Por isso, criei uma documentação completa e atualizada para o usuário final em inglês. Fui selecionado no Outreachy na organização Perl & Raku para a rodada de maio a agosto de 2020 como desenvolvedor de back-end do servidor do Open Food Facts. Além do desenvolvimento de back-end, uma das principais tarefas deste estágio é criar documentação para módulos e funções no formato POD. Entrei no mundo do código aberto no ano passado, quando contribuí para alguns projetos de código aberto e participei da Google Season of Docs. E este ano, fui selecionado no Outreachy, que apoia a diversidade em software de código aberto e sem custo financeiro. Tenho um bom domínio do Git, já que meu projeto do Outreachy está hospedado no GitHub e faço contribuições regulares para o Open Food Facts e o Mozilla Fenix desde março. Sou usuário do Linux há mais de três anos e uso comandos de terminal desde então.

As ferramentas e linguagens de documentação que usei são Sphinx, Read the docs e Markdown. Gostei dessa ideia e quero trabalhar nela porque tenho experiência relevante e adoraria usar meus conhecimentos e habilidades para contribuir com a DIPY. Tenho experiência no campo de processamento de imagens digitais, visão computacional e aprendizado de máquina. Isso vai me ajudar a entender melhor a neuroimagem e a criar a documentação. Tenho vasta experiência na área médica. Desenvolvi um site médico para médicos, pacientes, laboratórios, motoristas de ambulância. Trabalhei em outro sistema usado por médicos, pacientes, enfermeiros, assistentes de laboratório e pesquisadores. Isso vai me ajudar a criar uma documentação que será mais fácil de entender pelo público.

Analisei a documentação do DIPY e notei várias falhas nela. Há várias lacunas na documentação que pretendo melhorar. Estado atual da documentação: A documentação não tem uma estrutura e um design específicos Ela pode ser tediosa e demorada, especialmente para novos usuários Os usuários podem ter dificuldade para encontrar informações no guia O conteúdo da documentação precisa ser melhorado Como novo usuário, tive dificuldade para acessar o guia do usuário e o guia do desenvolvedor. A documentação precisa ser remodelada de forma que as informações exigidas pelo usuário sejam facilmente acessíveis A documentação não tem consistência

Pretendo fazer o seguinte:

Definir uma estrutura e um modelo específicos para a documentação Reformar a documentação para que os usuários possam navegar e encontrar facilmente as informações necessárias Produzir um cronograma ou uma lista de itens de trabalho para envolver a comunidade em outros trabalhos de documentação Definir modelos para o guia do usuário e do desenvolvedor Definir modelos para o guia de contribuição Reescrever, reestruturar e atualizar o guia do usuário, o guia de desenvolvimento e o guia de contribuição (que podem ajudar e motivar novos usuários a contribuir com o projeto) Adicionar imagens não textuais para melhorar as explicações textuais Melhorar a consistência em toda a documentação Criar documentação para a nova interface de linha de comando

Guia do usuário:

Para o guia do usuário, eu me concentraria em usar uma linguagem simples e clara para ajudar os usuários a entender até mesmo os sistemas mais complexos. Jargões, siglas e outras informações privilegiadas que um novo usuário pode não conhecer seriam evitados para melhorar a experiência do usuário. Também vou me concentrar no uso de conteúdo visual, incluindo imagens, capturas de tela anotadas, gráficos e vídeos, que mostram rapidamente ao usuário como o sistema funciona. Uma boa documentação precisa de uma hierarquia de títulos e subtítulos que permitam que o usuário saiba o que cada seção vai mostrar. Essa hierarquia precisa seguir um fluxo lógico que ajude o usuário a aprender a usar o sistema da maneira mais útil. Um dos principais objetivos desse projeto é criar conteúdo acessível. Todos os documentos e guias teriam um estilo consistente. É essencial usar fontes consistentes e cores complementares em vários documentos. Vou garantir que os usuários tenham acesso a mais recursos da organização sobre como ter sucesso com o sistema.

Guia para desenvolvedores:

O guia para desenvolvedores inclui orientações abrangentes e materiais de referência para ajudar o desenvolvedor a criar contribuições para o código-fonte do DIPY. Ele tenta mostrar as várias opções disponíveis para que você possa usar a abordagem certa, dependendo do que você quer alcançar. O guia de desenvolvimento precisa ser remodelado e reestruturado. Reescreverei o conteúdo do guia para desenvolvedores. A criação de dependências, o guia de contribuição, o guia de estilo, as convenções de programação, o guia de documentação, a instalação do ambiente de desenvolvimento, a depuração, o guia de teste e outros materiais relacionados serão incluídos e disponibilizados facilmente para os desenvolvedores. Quando novos colaboradores ansiosos se apressam para fazer sua primeira contribuição de código aberto no seu projeto, eles dependem das diretrizes de contribuição para se guiar. Assim, as diretrizes seriam fáceis de ler, completas e amigáveis. Os guias de contribuição são documentos úteis que explicam como as pessoas podem contribuir com o projeto de código aberto. Contribuir com o projeto deve ser o mais fácil e transparente possível para os usuários, seja: Enviar uma correção Informar um bug Tornar-se um mantenedor Discutir o estado atual do código Propor novos recursos

TEMPLATE

Este é um dos modelos que podem ser usados para o guia de contribuição. Ela pode ser modificada, e as seções podem ser adicionadas ou removidas de acordo com os requisitos do documento.

Como contribuir com o DIPY

• Nota de boas-vindas

TOC

Código de conduta

• Nossos padrões
• Exemplos de comportamento que contribuem para a criação de um ambiente positivo
• Exemplos de comportamento inaceitável dos participantes
• Nossas responsabilidades
• Responsabilidades dos mantenedores do projeto
• Escopo

Escopo do Código de Conduta

O que preciso saber para ajudar?

Se você quiser ajudar com uma contribuição de código, nosso projeto usa [inserir lista de linguagens de programação, frameworks ou ferramentas que seu projeto usa]. Se você ainda não se sente pronto para contribuir com código, não tem problema. Você também pode conferir os problemas de documentação [link para o rótulo ou a tag de documentos no Issue Tracker] ou os problemas de design que temos [link para o rótulo ou a tag de design no Issue Tracker se o projeto rastreia problemas de design]. Se você tem interesse em contribuir com código e quer saber mais sobre as tecnologias que usamos, confira a lista abaixo. Inclua uma lista de recursos (tutoriais, vídeos, livros) que os novos colaboradores podem usar para saber o que os usuários precisam saber para contribuir com o projeto.

Como configurar o ambiente de desenvolvimento

Nesta seção, vou adicionar o procedimento de instalação e as dependências que precisam ser instaladas. Instale $project executando: install project

• Código-fonte: github.com/$project/$project
• Rastreador de problemas: github.com/$project/$project/issues

Como contribuir

Como informar um bug

• Antes de enviar um relatório de bug
• How Do I Submit A (Good) Bug Report?

Como enviar mudanças

• Protocolos de solicitação de pull
• Resposta da equipe
• Velocidade de resposta

Como solicitar uma melhoria

• Antes de enviar uma sugestão de melhoria
• How Do I Submit A (Good) Enhancement Suggestion?

Sua primeira contribuição de código

• Problemas para iniciantes
• Problemas de ajuda necessária #### Solicitação de envio
• Processo de criação de uma solicitação de envio
• Verifique se todas as verificações de status estão sendo aprovadas.

E se as verificações de status estiverem falhando?

• Como programar testes
• Cobertura de teste

Guias de estilo

• Mensagens de confirmação do Git
• Estilo padrão

Suporte

Se tiver problemas, entre em contato. Se precisar de ajuda, faça perguntas na nossa lista de e-mails em [e-mail], no chat do IRC ou em [liste outras plataformas de comunicação usadas pelo seu projeto].

Licença

Esta seção vai falar sobre a licença do projeto.

Compromisso de tempo e comunicação:

Vou trabalhar mais de 45 horas por semana, mas, em caso de algum problema, vou compensar essas horas nos fins de semana. Durante o período de vinculação à comunidade, vou discutir os meios de comunicação e finalizar as reuniões semanais, os meios e o horário com meu mentor. Vou manter meu mentor atualizado sobre meu trabalho e compartilhar os detalhes por e-mail. Prefiro usar o TeamViewer para comunicação, já que ele é fácil de usar e tem muitos recursos, como telas de compartilhamento etc.