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:
- CERN-HSF
- Redator técnico:
- LuckInTheRain
- Nome do projeto:
- Documentação do ROOT: como analisar, reestruturar e reescrever
- Duração do projeto:
- De longa duração (5 meses)
Project description
O projeto consiste em quatro fases:
1.) Como analisar a documentação atual da ROOT
O documento ROOT completo (site, guia do usuário, referência do C++, tutoriais etc.) é analisado e verificado de acordo com os seguintes critérios: estrutura, modularização, padronização, mecanismos de acesso, consistência, tipos de informações usados, preparação específica para o grupo-alvo e compreensão. O objetivo é criar um conceito para o gerenciamento de informações, uma matriz para estruturar e uma diretriz para padronizar o conteúdo.
2.) Como definir um método para estruturar a documentação de um software de escrita com a equipe do ROOT
O DITA (Darwin Information Typing Architecture), um padrão OASIS para documentação de software (https://www.oasis-open.org/committees/dita/), é apresentado à equipe ROOT. O foco principal é entender como estruturar conteúdo específico do software e como tipos de informações elementares, como "conceito", "tarefa" e "referência", são usados para escrever a documentação do software.
3.) Reestruturação e reorganização da documentação do ROOT
Com base nos resultados das duas primeiras etapas, a documentação da ROOT é reestruturada e modularizada de acordo com grupos-alvo, funções e casos de uso, e o conteúdo é atribuído aos elementos correspondentes (site, guia do usuário, referência C++, tutoriais etc.) e tipos de conteúdo. Como as informações disponíveis são muito extensas, também é necessário estabelecer uma estrutura de referência consistente. O objetivo é fornecer uma visão geral abrangente e mostrar aos usuários maneiras claras de usar o ROOT para atender às necessidades deles. Além disso, uma introdução compacta não orientada à física é fornecida.
4.) Reescrever a documentação da ROOT
As partes principais da documentação, especialmente o guia do usuário, são reescritas de acordo com a abordagem DITA. As regras de estruturação e redação são registradas em um guia de estilo para garantir a consistência dos documentos no futuro. O objetivo é permitir que a equipe ROOT estenda e mantenha a documentação ROOT por conta própria no futuro.
Cronograma estimado (cinco meses):
Fase 1: analisar a documentação atual do ROOT: 3 semanas.
Fase 2: definir um método para estruturar a documentação de um software de escrita com a equipe ROOT (duas semanas).
Fase 3: reestruturação e reorganização da documentação ROOT: 4 semanas.
Fase 4: reescrever a documentação ROOT: 11 semanas.