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:
- LuckInTheRain
- Nome do projeto:
- Documentação ROOT: análise, reestruturação e reescrita
- 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 do ROOT
O documento ROOT completo (site, guia do usuário, referência C++, tutoriais etc.) é analisado e verificado de acordo com os seguintes critérios: estruturação, modularização, padronização, mecanismos de acesso, consistência, tipos de informações usados, preparação e compreensão do grupo-alvo. O objetivo é criar um conceito para o gerenciamento de informações, uma matriz de estruturação e uma diretriz para padronizar o conteúdo.
2.) Definir um método para estruturar uma documentação de software de escrita com a equipe de ROOT
DITA (Darwin Information Typing Architecture), um padrão OASIA para documentação de software (https://www.oasis-open.org/committees/dita/), é apresentado à equipe ROOT. O foco principal é entender como estruturar o conteúdo específico do software e como os tipos de informações básicas como “conceito”, “tarefa” e “referência” são usados para escrever a documentação de software.
3.) Reestruturação e reorganização da documentação ROOT
Com base nos resultados das duas primeiras etapas, a documentação ROOT é reestruturada e modularizada de acordo com grupos de destino, papéis 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 deve ser estabelecida uma estrutura de referência consistente. O objetivo é oferecer uma visão geral abrangente e mostrar aos usuários formas claras de como usar a ROOT de acordo com as necessidades deles. Além disso, uma introdução compacta não orientada à física é fornecida.
4.) Como reescrever a documentação ROOT
As principais partes da documentação, especialmente o Guia do usuário, foram reescritas de acordo com a abordagem DITA. As regras de estruturação e escrita são registradas em um Guia de estilo para garantir a consistência nos documentos no futuro. O objetivo é permitir que a equipe ROOT estenda e mantenha a documentação ROOT no futuro.
Cronograma estimado (5 meses):
Fase 1: analisar a documentação ROOT atual: três semanas
Fase 2: definição de um método para estruturar a documentação de um software de redação com a equipe de ROOT: duas semanas
Fase 3: reestruturação e reorganização da documentação ROOT (quatro semanas).
Fase 4: reescrever a documentação ROOT: 11 semanas