Projeto DIPY

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:

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

Project description

Sou engenheiro de software e tenho experiência em escrita 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. Eu moro em Islamabad, Paquistão (fuso horário: UTC + 5). Atualmente, estou trabalhando como estagiário no Apoio, que vai continuar até 18 de agosto. Participei da temporada de Documentos Google 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 selecionada para a Integração no app Contatos na organização Perl & Raku, de maio a agosto de 2020, como desenvolvedor de back-end do servidor do Open Food Facts. Além do desenvolvimento back-end, uma das principais tarefas do 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 Google. E este ano, fui selecionado na plataforma plataforma, que apoia a diversidade em softwares de código aberto e sem custos financeiros. Tenho um ótimo controle sobre o Git porque meu projeto de contato 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 3 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 e Markdown. Gostei da 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 de imagens digitais, visão computacional e aprendizado de máquina. Ele vai 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 para o 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. Estado 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 encontrar 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

Planejo 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 e encontrar facilmente as informações necessárias Produza um roteiro 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 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 pode ajudar e motivar novos usuários a contribuir para a nova interface para aprimorar a documentação da documentação - Aprimorar a consistência da documentação para a documentação do projeto)

Guia do usuário:

Para o guia do usuário, meu foco seria usar uma linguagem simples e simples para ajudar os usuários a entender até mesmo os sistemas mais complexos. Para melhorar a experiência do usuário, evitamos jargões, siglas e outras informações privilegiadas que um novo usuário talvez não conheça. Também vou me concentrar no uso de conteúdo visual, incluindo imagens, capturas de tela anotadas, gráficos e vídeos, que mostrem rapidamente ao usuário como o sistema funciona. Uma boa documentação precisa de uma hierarquia de cabeçalhos e subtítulos para que o usuário saiba 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 devem aderir a um estilo consistente. Usar fontes consistentes e cores complementares em vários documentos é imprescindível. Vou garantir que os usuários tenham acesso a mais recursos da organização para ter sucesso com o sistema.

Guia do desenvolvedor:

O guia do desenvolvedor inclui orientações e materiais de referência abrangentes para ajudar o desenvolvedor a criar 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. A criação de dependências, o guia de contribuição, o guia de estilo, as convenções de codificação, o guia de documentação, a instalação do ambiente de desenvolvimento, a depuração, o guia de teste e itens relacionados serão incluídos e ficarão facilmente acessíveis para os desenvolvedores. Quando novos colaboradores ansiosos chegam ao seu projeto para fazer a primeira contribuição de código aberto, eles dependem das diretrizes de contribuição como orientação. Assim, 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 deve ser o mais fácil e transparente possível para os usuários, seja: enviar uma correção Informar um bug Ser 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. Ele pode ser modificado, e é possível adicionar ou remover seções de acordo com os requisitos do documento.

Contribuir para o DIPY

• Nota de recepção

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 você 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 a tag dos documentos no seu Issue Tracker] ou os problemas de design que temos [link para o rótulo de design ou a tag 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 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, 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 relatório de bugs (bom)?

Como enviar 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 aprimoramento?

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
• Confira 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 você 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 no seu projeto].

Licença

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

Tempo dedicado e comunicação:

Vou dar 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 com a comunidade, vou discutir os meios de comunicação e finalizar reuniões semanais, meios e tempo para essas reuniões com meu mentor. Vou manter meu mentor atualizado sobre meu trabalho e compartilhar os detalhes de trabalho por e-mail com ele. Prefiro o TeamViewer para comunicação, já que é fácil de usar e com muitos recursos como telas de compartilhamento, etc.