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:
- CERN-HSF
- Redator técnico:
- SabitaR
- Nome do projeto:
- Reestruturação e simplificação da documentação da Allpix Squared
- Duração do projeto:
- Duração padrão (3 meses)
Project description
VISÃO GERAL Escolhei o projeto Allpix Squared da CERN-HSF por dois motivos principais:
Desenvolvimento de habilidades: a documentação atual deste projeto é abrangente e integra vários formatos de conteúdo. A auditoria e a reestruturação desse conjunto abrangente de documentos me ajudarão a melhorar minha arquitetura de informações e minhas habilidades de escrita. Além disso, o domínio do projeto (física de partículas!) é uma novidade para mim. Ele me desafia a aprimorar minhas habilidades de interação com desenvolvedor. Acredito que os redatores técnicos podem processar as informações dos desenvolvedores e apresentar conteúdo útil para qualquer nível de usuário, SE fizermos a pesquisa de histórico necessária e fizermos as perguntas certas. Este projeto vai me deixar testar essa teoria!
Conhecimento técnico: este projeto exige o Hugo, uma ferramenta que está no topo da minha lista de aprendizado. Estou ansioso para aprender o fluxo de trabalho LaTeX-Markdown-Hugo-GitLab-CI.
Durante a fase de exploração técnica do redator, interagi com os mentores do projeto brevemente e me familiarize com a estrutura do pacote de documentos existente. Também criei um site de demonstração (https://ap2-demo.netlify.app/) para testar se consigo configurar o Hugo e o Docsy corretamente no meu computador Windows. Consegui implantar o site no Netlify, mas não nas páginas do Gitlab. Para que este projeto mantenha o fluxo de trabalho de implantação atual, vou encontrar uma maneira de implantar o tema Hugo Docsy nas páginas do Gitlab.
RESULTADOS ESPECÍFICOS DO PROJETO - Um site simplificado de projeto que integra documentação, referência de código, tutoriais e notícias. - Um manual do usuário reestruturado e revisado que separa o conteúdo destinado a usuários e desenvolvedores e inclui informações ausentes. - Um fluxo de trabalho de tutoriais com exemplos disponíveis de documentação de instruções, perguntas frequentes e problemas mais comuns.
FERRAMENTAS DE PROJETO A documentação atual da Allpix Squared usa LaTeX, Doxygen, pandoc e Hugo, além do GitLab e do Gitlab CI. Os mentores do projeto e eu conversamos sobre a possibilidade de mover o conteúdo de LaTeX para Markdown com plug-ins do MathJax. Se eu conseguir, o fluxo de trabalho do documento vai envolver Hugo, Markdown, Doxygen, git e Gitlab CI. Para manter os tutoriais no mesmo site/plataforma, vou usar Hugo e Markdown. Gostaria de saber se é possível usar o codelab como ferramenta (ClaaT) para tutoriais. Em julho, espero testar o fluxo de trabalho ClaaT-Hugo e conversar sobre ele com os mentores, caso tenham sido selecionados.
DURAÇÃO DO PROJETO Estou solicitando a conclusão do projeto Allpix Squared dentro do período padrão de três meses (14 de setembro de 2020 a 30 de novembro de 2020), durante o qual passarei cerca de 15 horas por semana. Esse horário incluirá reuniões com mentores e e-mails relacionados, conforme necessário. Eu também vou seguir os cronogramas do GSoD para vínculo com a comunidade e finalização do projeto.
TAREFAS DO PROJETO Veja como pretendo implementar minhas atualizações propostas para o conjunto de documentos existente da Allpix Squared: 1. Pesquise, converse e explore as opções (17 de agosto a 13 de setembro de 2020): - Entender os requisitos do projeto - Instalar o software Allpix Squared para identificar, se houver, informações ausentes nos documentos atuais. - Solicite as credenciais necessárias. - Criar fluxos de trabalho de usuários para diferentes usuários do Allpix Squared - Classificar conteúdo por função do usuário - Verificar as implicações da conversão de arquivos LaTeX para Markdown - Consolidar repositórios de origem ou entender como trabalhar com vários repositórios git - Bônus: testar o CLaaT como opção para tutoriais - Bônus: crie uma referência rápida de guia de estilo de tempo/shortcodes para ajudar os colaboradores a manter os documentos
Reestruturar, revisar e melhorar o conteúdo (14 de setembro a 19 de outubro de 2020): duas tarefas por semana, aproximadamente de cinco a sete horas por tarefa. Esse cronograma inclui uma semana de reserva para lidar com atrasos ou problemas inesperados.
- Revisar o conteúdo atual e as classificações dos usuários considerando os fluxos de trabalho
- Descrever e testar o fluxo de trabalho de conteúdo reestruturado para diferentes usuários
- Fornecer e melhorar conteúdo ausente
- Converter arquivos LaTeX para Markdown
- Finalizar o guia do usuário e o índice do guia do desenvolvedor
- Gere PDFs de guias do usuário e do desenvolvedor
- Bônus: estruture o conteúdo para tutoriais com exemplos e problemas
- Bônus: configure um fluxo de trabalho de tutorial com exemplos de instruções Cronograma: cinco semanas (fase de desenvolvimento do Doc)
Crie o site (19 de outubro a 30 de novembro de 2020): 1 a 2 tarefas por semana, aproximadamente 5 a 7 horas por tarefa. Este cronograma inclui uma semana de espera para solucionar problemas e ajustar a saída final.
- Entender e testar o fluxo de trabalho de publicação
- Criar uma estrutura de site usando Hugo e Docsy
- Testar como manter a implantação automática e o fluxo de trabalho atuais usando o Docsy
- Extrair conteúdo do Doxygen
- Desenvolva manual do usuário, guia do desenvolvedor e tutoriais com base no conteúdo LaTex ou Markdown
- Finalizar a aparência do site do projeto (logotipo, cores, modelo, layout, links, usabilidade e CI/CD do Gitlab) Cronograma: seis semanas (fase de desenvolvimento do Doc)