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:
- Kolibri
- Redator técnico:
- StephDix
- Nome do projeto:
- Estilo de documentação e convenções de fluxos de trabalho do ecossistema Kolibri
- Duração do projeto:
- Longa duração (cinco meses)
Project description
Resumo
Este documento detalha a implementação das diretrizes de estilo e o gerenciamento de fluxo de trabalho para as informações documentadas do Learning Equality sobre o projeto do ecossistema Kolibri.
Visão geral
Minha proposta consiste em quatro fases. Na primeira fase, vou preencher o Guia de estilo da documentação de LE com diretrizes de acessibilidade, escrita e recomendações de formato seguindo os conceitos e diretrizes de estilo de LE no desenvolvimento de software. Na segunda fase, vou realizar uma auditoria de qualidade nos documentos do ReadTheDocs e do Google Docs. O plano de auditoria integra o uso de listas de verificação para avaliar a conformidade com as diretrizes de estilo. Essas listas de verificação ajudarão a registrar as descobertas e aplicar alterações à documentação. Na terceira fase, vou trabalhar na estrutura, aparência e sensação dos modelos dos documentos do ReadTheDocs e dos Documentos Google. Vou criar um repositório de modelos e imagens no Google Drive, identificando cada categoria de modelo dos principais tipos de documento para reutilização em implementações futuras. Vou complementar essa tarefa criando modelos para enviar problemas com documentos que facilitam a identificação em análises de solicitações de envio. Por fim, vou criar um guia para colaboradores que vai agrupar recursos úteis para cada grupo de colaboradores melhorar a experiência de acesso às informações.
Propósito e escopo
A intenção por trás desse plano de implementação é melhorar a experiência dos usuários finais que usam os documentos da Kolibri e ajudar os membros da equipe e os colaboradores a produzir melhor documentação e colaboração ativa na comunidade. Essa implementação se aplica ao ReadTheDocs e a subconjuntos de documentos do Documentos Google no ecossistema Kolibri.
Público-alvo
Um público-alvo principal de implementadores, administradores e usuários finais, que são os consumidores mais importantes da documentação do Kolibri. Um público secundário de membros da equipe e colaboradores para a produção e uso da documentação de Kolibri.
Objetivos
O guia de estilo e o sistema de fluxo de trabalho da documentação do ecossistema Kolibri esperam que os usuários: Criem uma documentação fácil de entender com linguagem acessível e layout consistente. Manter práticas de qualidade na documentação. Facilitar o acesso às informações entre os canais de documentação. Reforçar as iniciativas colaborativas na comunidade de código aberto Kolibri.
Fontes de informações
Minhas fontes de informação foram Kolibri, Kolibri Studio, documentos de RTD do desenvolvimento do Kolibri e Kolibri Toolkits do Google Drive.
A maravilhosa Radina Matic foi de grande ajuda para fornecer atividades de aquecimento e atividades específicas para projetos. A contribuição dela sobre o que a organização conceitua como "diretrizes" e "guias" e a existência de um guia para colaboradores me ajudaram a organizar minhas ideias e elaborar conclusões.
Software
Vou desenvolver o rascunho do guia de estilo nos Documentos Google. Essa plataforma de documentos é perfeita para iterar enquanto está pronta para publicação. Para a auditoria de controle de qualidade, vou usar o Google Forms para conduzir e avaliar os documentos. Uma planilha vai armazenar as respostas do formulário para controle de documentos. Refatorar os documentos de RTD usando o GitHub. Já trabalhei com Git, Gitkraken, GitHub e Gitlab. Tenho conhecimento prático de Markdown e alguns RestructuredText. Estou planejando contribuir com correções na documentação para continuar aprendendo a sintaxe. Vou usar o Sharex para imagens e GIFs. Adoro essa ferramenta porque ela renderiza em diferentes formatos de saída. Vou usar o app Diagrams para criar diagramas e editar imagens. O software de diagramas se integra perfeitamente ao Documentos Google, ao Google Drive e ao LibreOffice. Estado da documentação Na fase de exploração, revisei a maior parte da documentação do Kolibri. Encontrei erros gramaticais, erros de digitação, inconsistências no layout, na tipografia, no uso de imagens e também caminhos de documentação confusos na maior parte da documentação do projeto. Por exemplo, no guia do usuário do Kolibri, a seção de solução de problemas é um subtópico, e não um tópico. Essas informações são importantes o suficiente para que os usuários finais tenham acesso a elas na tabela de conteúdos. Como segunda alternativa, eles podem usar a barra de pesquisa e a árvore de conteúdo para expandir outros tópicos e localizar artigos de solução de problemas.
Para acessar a seção "Solução de problemas", você precisa pesquisar ou expandir "Gerenciar Kolibri" para saber que a solução de problemas faz parte da documentação. Guia x diretrizes Para esta proposta de projeto, analisei dois documentos: o guia de estilo da documentação do usuário do LE Kolibri e as diretrizes de tradução do LE. No guia Kolibri do LE, fiz recomendações e comentários com base no plano de documentação e no esboço de tópicos propostos, além de outras poucas coisas que precisam ser melhoradas no guia. Para as diretrizes de tradução de LE, mudei o formato e o estilo com base nas minhas recomendações e nas convenções existentes no guia de estilo. O que mais me chamou a atenção durante a análise foi a concepção errônea entre os documentos categorizados como Guia e Diretrizes.
Resultados
Fiz uma verificação de qualidade do guia de tradução de LE, além de sugestões e comentários com um formulário preliminar que explico com mais detalhes na tarefa de auditoria de qualidade. Estes são alguns comentários finais recebidos da avaliação: Links corrompidos do site de sintaxe .js da ICU. O formato usado para criar essas diretrizes está incorreto. O documento é um guia, não diretrizes. Tipografia inconsistente. Uso incorreto de títulos e legendas, uso inadequado da linguagem e uso indevido de contrações. Uso indevido de textos alternativos. Por instruções/ declarações repetidas.
As descobertas de ambos os documentos fazem parte dos resultados desta proposta.
Tarefas específicas do projeto
- Recomendações do guia de estilo da documentação do usuário da LE (comentários)
- Diretrizes de tradução de LE com novos estilos e formato.
- Resumo dos tópicos
- Cronograma do projeto
- Tarefas de documentação