Projeto DIPY

Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:

DIPY

(em inglês)

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 (3 meses)

Project description

Sou engenheiro de software e tenho experiência em redação técnica. Tenho mais de 4 anos de experiência na criação de documentação de software de alta qualidade, guias do usuário, manuais e descrições de projetos. Moro em Islamabad, Paquistão (fuso horário: UTC + 5). Atualmente, estou trabalhando como estagiário na Outreachy, que continuará até 18 de agosto. Participei da Temporada do Google Docs como redator técnico na organização OpenELIS Global. A documentação original estava em francês, limitada e desatualizada, então criei uma documentação para o usuário final extensa e atualizada em inglês. Fui selecionado no Outreachy, da organização Perl & Raku, de maio a agosto de 2020, como desenvolvedor de back-end do servidor 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 ano passado quando contribuí com alguns projetos de código aberto e, mais tarde, participei da temporada de documentos do Google. Neste 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 Outreachy está hospedado no GitHub. Tenho feito 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 tenho usado comandos de terminal desde então.

As ferramentas de documentação e linguagens que usei são Sphinx, Read the docs, Markdown. Gostei dessa ideia e quero trabalhar nela porque tenho experiência relevante e adoraria usar meus conhecimentos e habilidades para contribuir com o DIPY. Tenho experiência na área de processamento digital de imagens, visão computacional e aprendizado de máquina. Ele me ajudará a entender melhor as neuroimagens e a criar documentação. Tenho vasta experiência na área médica. Desenvolvi um site médico para médicos, pacientes, laboratórios e 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 seja mais fácil de entender pelo público.

Analisei a documentação do DIPY e anotei várias falhas na documentação. Há várias brechas na documentação que pretendo melhorar. Situação atual da documentação: a documentação não tem estrutura e design específicos A navegação pode ser tediosa e demorada, principalmente para os novos usuários. Os usuários podem ter dificuldade para acessar as informações do guia O conteúdo da documentação precisa ser aprimorado Como novo usuário, achei difícil acessar o guia do usuário e o guia para desenvolvedores. A documentação precisa ser remodelada de modo 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 Reformule a documentação para que os usuários possam navegar facilmente e encontrar as informações necessárias Produzir um roteiro ou uma lista de itens de trabalho para envolver a comunidade no trabalho posterior da documentação Definir modelos para o guia do usuário e o guia 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 os novos usuários a contribuir para a nova documentação de linha de comando para aprimorar a documentação não textual)

Guia do usuário:

Para o guia do usuário, eu me concentraria no uso de 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 internas que um novo usuário talvez não conheça seriam evitadas para uma melhor 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 permita ao usuário saber o que cada seção mostrará. E essa hierarquia deve seguir um fluxo lógico que ajuda o usuário a aprender a usar o sistema da maneira mais útil. Um dos principais objetivos deste projeto seria criar conteúdo acessível. Todos os documentos e guias seguem um estilo consistente. O uso de fontes consistentes e cores complementares em vários documentos é obrigatório. Vou garantir que os usuários tenham acesso a mais recursos da organização sobre como ter sucesso com o sistema.

Guia do desenvolvedor:

O guia do desenvolvedor inclui materiais de orientação e referência abrangentes para ajudar o desenvolvedor na criação de contribuições para o código-fonte do DIPY. Ele tenta apresentar as várias opções disponíveis, para que você possa usar a abordagem correta, dependendo do que pretende alcançar. O guia de desenvolvimento precisa ser remodelado e reestruturado. Vou reescrever o conteúdo do guia do desenvolvedor. Dependências de criação, guia de contribuição, guia de estilo, convenções de codificação, guia de documentação, instalação de ambiente de desenvolvimento, depuração, guia de teste e itens relacionados serão incluídos e ficarão facilmente acessíveis para os desenvolvedores. Quando novos colaboradores ansiosos se acessam em seu projeto para fazer sua primeira contribuição de código aberto, eles contam com as diretrizes de contribuição como orientação. Portanto, as diretrizes seriam fáceis de ler, completas e amigáveis. Guias de contribuição são documentos úteis que comunicam como as pessoas podem contribuir com o projeto de código aberto. A contribuição para o projeto precisa ser a 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 no guia de contribuição. É possível modificar e adicionar ou remover seções de acordo com os requisitos do documento.

Contribuir para DIPY

• Nota de boas-vindas

TOC

Código de conduta

• Nossos padrões
• Exemplos de comportamentos 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ê quer ajudar com uma contribuição de código, nosso projeto usa [insira a lista de linguagens de programação, frameworks ou ferramentas que seu projeto usa]. Se ainda não quiser contribuir com um código, não tem problema. Você também pode conferir os problemas de documentação [link para a etiqueta ou tag dos 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 rastrear problemas de design]. Se você tem interesse em fazer uma contribuição de 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 possam usar para saber o que os usuários precisam saber para contribuir com o projeto.

Como configurar o ambiente de desenvolvimento

Nesta seção, adicionarei 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
• Issue Tracker: github.com/$project/$project/issues

Como colaborar

Como informar um bug

• Antes de enviar um relatório de bugs
• Como envio um bom relatório de bugs?

Como enviar as mudanças

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

Como solicitar uma melhoria

• Antes de enviar uma sugestão de melhoria
• Como envio uma (boa) sugestão de melhoria?

Sua primeira contribuição de código

• Problemas para iniciantes
• Problemas solicitados #### 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 estiver tendo problemas, entre em contato conosco. Se precisar de ajuda, faça perguntas na nossa lista de e-mails localizada em: [e-mail], chat do IRC ou [liste outras plataformas de comunicação usadas por seu projeto].

Licença

Esta seção informará sobre a licença do projeto.

Compromisso de tempo e comunicação:

Farei mais de 45 horas por semana, mas, em caso de contratempo, compensarei essas horas nos fins de semana. Durante o período de vínculo comunitário, discutirei os meios de comunicação e finalizarei as reuniões semanais, os meios e o tempo dessas reuniões com meu mentor. Vou manter o mentor atualizado sobre meu trabalho e compartilhar os detalhes do trabalho por e-mail com ele. Prefiro o TeamViewer para comunicação, já que ele é fácil de usar e tem muitos recursos, como compartilhar telas.