Esta página contém os detalhes de um projeto de escrita técnica aceito para o Temporada dos Documentos 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 do Allpix Squared
- Duração do projeto:
- Duração padrão (três meses)
Project description
CONTEXTO Escolhi o projeto Allpix Squared do CERN-HSF por dois motivos principais:
Desenvolvimento de habilidades: a documentação atual do projeto é abrangente e integra vários formatos de conteúdo. Auditar e reestruturar esse extenso conjunto de documentos me ajudará a aprimorar minhas habilidades de redação e arquitetura de informações. Além disso, o domínio do projeto (física de partículas!) é novo para mim. Ele me desafia a aprimorar minhas habilidades de interação com desenvolvedores. 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, desde que façamos a pesquisa de antecedentes necessária e façamos 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 coisas a aprender. Estou ansioso para aprender o fluxo de trabalho LaTeX-Markdown-Hugo-GitLab-CI.
Durante a fase de exploração do redator técnico, interagi brevemente com os mentores do projeto e me familiarizei com a estrutura de 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 na minha máquina Windows. Consegui implantar o site no Netlify, mas não no Gitlab Pages. Para manter o fluxo de implantação atual do projeto, vou encontrar uma maneira de implantar o tema Hugo Docsy no Gitlab Pages.
RESULTADOS DO PROJETO ESPERADOS - Um site de projeto simplificado 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 que faltavam anteriormente. - Um fluxo de trabalho de tutoriais com exemplos disponíveis de documentação com instruções, perguntas frequentes e problemas comuns.
FERRAMENTAS DO PROJETO A documentação atual do 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 transferir conteúdo de LaTeX para Markdown com os plug-ins do MathJax. Se eu conseguir, o fluxo de trabalho do documento envolverá Hugo, Markdown, Doxygen, git e Gitlab CI. Para manter os tutoriais no mesmo site/plataforma, vou usar o Hugo e o Markdown. Tenho dúvidas sobre a viabilidade de usar o Codelabs-as-a-Tool (ClaaT) para tutoriais. Em julho, espero testar o fluxo de trabalho do ClaaT-Hugo e discutir com os mentores, se selecionado.
DURAÇÃO DO PROJETO Estou solicitando a conclusão do projeto Allpix Squared no período padrão de três meses (14 de setembro a 30 de novembro de 2020), durante o qual vou dedicar aproximadamente 15 horas por semana. Essas horas incluem reuniões com mentor e e-mails relacionados, conforme necessário. Vou seguir os prazos do GSoD para a integração da comunidade e a finalização do projeto.
TAREFAS DO PROJETO Veja como pretendo implementar minhas atualizações propostas para o pacote de documentos da Allpix Squared: 1. Pesquise, discuta e conheça as opções (17 de agosto a 13 de setembro de 2020): - Entenda os requisitos do projeto - Instale o software Allpix Squared para identificar informações ausentes nos documentos atuais. - Solicite as credenciais necessárias. - Criar fluxos de trabalho para diferentes usuários do Allpix Squared - Classificar o conteúdo por função do usuário - Verificar as implicações da conversão de arquivos LaTeX em Markdown - Consolidar repositórios de origem ou entender como trabalhar com vários repositórios do Git - Bônus: testar o CLaaT como uma opção para tutoriais - Bônus: criar uma referência rápida de guia de estilo/shortcodes para ajudar os colaboradores a manter os documentos Cronograma: fase de integração da comunidade
Reestruture, revise e aprimore o conteúdo (14 de setembro a 19 de outubro de 2020): Duas tarefas por semana, cerca de 5 a 7 horas por tarefa. Essa linha do tempo inclui uma semana de buffer para lidar com atrasos ou problemas inesperados.
- Analisar o conteúdo e as classificações de usuários atuais pensando nos fluxos de trabalho dos usuários
- Descrever e testar o fluxo de trabalho de conteúdo reestruturado para diferentes usuários
- Fornecer e melhorar o conteúdo ausente
- Converter arquivos LaTeX em Markdown
- Finalizar o sumário do guia do usuário e do guia do desenvolvedor
- Gerar PDFs dos guias para usuários e desenvolvedores
- Bônus: estruturar o conteúdo de tutoriais com base em exemplos e problemas
- Bônus: configurar um fluxo de trabalho de tutorial para exemplos de como fazer Cronograma: 5 semanas (fase de desenvolvimento de documentos)
Criar o site (19 de outubro a 30 de novembro de 2020): de 1 a 2 tarefas por semana, aproximadamente 5 a 7 horas por tarefa. Essa linha do tempo inclui uma semana de buffer para resolver problemas e ajustar a saída final.
- Entender e testar o fluxo de trabalho de publicação
- Criar uma estrutura de site usando o Hugo e o Docsy
- Testar como manter a implantação e o fluxo de trabalho automáticos atuais usando o Docsy
- Extrair conteúdo do Doxygen
- Desenvolva manual do usuário, guia do desenvolvedor e tutoriais de 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: 6 semanas (fase de desenvolvimento de documentos)