Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.
Resumo do projeto
- Organização de código aberto:
- CERN-HSF (em inglês)
- 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 de ROOT
O documento ROOT completo (site, guia do usuário, referência em 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 usadas, preparação e compreensão específicas do grupo-alvo. O objetivo é criar um conceito de gerenciamento de informações, uma matriz de estruturação e uma diretriz para padronizar o conteúdo.
2) Definição de um método para estruturar a documentação de um software de escrita com a equipe ROOT
A DITA (Darwin Information Typing Architecture), um padrão da OASIS para documentação de software (https://www.oasis-open.org/committees/dita/) é apresentada à equipe ROOT. O foco principal é entender como estruturar o conteúdo específico de software e como os tipos de informações elementares, como "conceito", "tarefa" e "referência" são usados para escrever a documentação de um 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-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 é oferecer uma visão geral abrangente e mostrar aos usuários maneiras claras de como usar ROOT para atender às necessidades deles. Além disso, é fornecida uma introdução compacta e não orientada à física.
4) 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: 2 semanas.
Fase 3: reestruturação e reorganização da documentação ROOT: quatro semanas.
Fase 4: reescrita da documentação ROOT: 11 semanas.