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:
- Kolibri (link em inglês)
- Redator técnico:
- StephDix
- Nome do projeto:
- Convenções de fluxos de trabalho e estilo de documentação do ecossistema Kolibri
- Duração do projeto:
- De longa duração (5 meses)
Project description
Com abstração
Neste documento, apresentamos a implementação das diretrizes de estilo e do gerenciamento de fluxos de trabalho nas informações documentadas da Learning Equality para o projeto Ecossistema da Kolibri.
Informações gerais
Minha proposta tem 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 do LE no desenvolvimento de software. Na segunda fase, realizarei uma auditoria de qualidade em documentos ReadTheDocs e GoogleDocs. O plano de auditoria integra o uso de listas de verificação para avaliar a conformidade com as diretrizes de estilo. As listas de verificação ajudarão a registrar as descobertas e aplicar alterações à documentação. Na terceira fase, vou trabalhar na estrutura e na aparência dos modelos de documentos ReadTheDocs e GoogleDocs. Criarei um repositório de modelos e imagens no Google Drive identificando cada categoria de modelo dos principais tipos de documentos para reutilização nas próximas implementações. Vou complementar essa tarefa criando modelos para apresentar problemas nos documentos, facilitando a identificação nas análises de solicitações pull. Por fim, criarei um Guia para colaboradores com recursos úteis para cada grupo de colaboradores, visando melhorar sua experiência ao acessar informações.
Finalidade e escopo
A intenção por trás desse plano de implementação é melhorar a experiência dos usuários finais com os documentos da Kolibri e ajudar os membros da equipe e colaboradores a produzir melhor documentação e colaboração ativa na comunidade. Essa implementação se aplica a ReadTheDocs e subconjuntos de documentos do Google Docs no ecossistema de Kolibri.
Público-alvo
O público principal de implementadores, administradores e usuários finais são os consumidores mais importantes da documentação do Kolibri. 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 para a documentação do ecossistema Kolibri esperam que os usuários: Criar uma documentação simples com linguagem acessível e layout consistente. Preservar a manutenção das práticas de qualidade após a documentação. Manter a facilidade de acesso às informações entre os canais de documentação. Reforçar as iniciativas colaborativas na comunidade de código aberto da Kolibri.
Fontes de informações
Minhas fontes de informação foram o Kolibri, o Kolibri Studio, os documentos de RTD de desenvolvimento da Kolibri e os kits de ferramentas da Kolibri do Google Drive.
A maravilhosa Radina Matic foi de grande ajuda nas atividades de aquecimento e atividades específicas do projeto. A contribuição dela sobre o que a organização conceitualiza como ""Diretrizes" e "Guias" e sobre a existência de um Guia para colaboradores me ajudou a organizar minhas ideias e elaborar conclusões.
Software
Vou desenvolver o rascunho do Guia de estilo no 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 app Formulários Google para conduzir e avaliar documentos. Uma planilha armazenará as respostas do formulário para controle do documento. Vou refatorar documentos RTD usando o GitHub. Já trabalhei com Git, Gitkraken, GitHub e Gitlab. Tenho conhecimento prático de Markdown e alguns RestructuredText. Quero contribuir para correções na documentação para continuar aprendendo a sintaxe. Usarei o Sharex para imagens e gifs. Eu adoro essa ferramenta porque ela é renderizada em diferentes formatos de saída. Vou usar diagramas para diagramação e edição de imagens. O software de diagramas se integra perfeitamente com o GoogleDocs, o Google Drive e o LibreOffice. Estado da documentação Na fase de análise detalhada, revisei a maior parte da documentação da Kolibri. Encontrei erros gramaticais, erros de digitação, inconsistências no layout, tipografia, uso de imagens e caminhos 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, não um tópico. Essas informações são essenciais o suficiente para que os usuários finais tenham acesso a elas no índice. Como segunda alternativa, eles podem usar a barra de pesquisa e a árvore do sumário para expandir outros tópicos e localizar artigos sobre solução de problemas.
Para acessar a seção "Solução de problemas", você precisa pesquisar ou abrir "Gerenciar o Kolibri" para perceber que a solução de problemas faz parte da documentação. Guia x diretrizes Para esta proposta de projeto, analisei dois documentos: Guia de estilo da documentação do usuário da LE Kolibri e Diretrizes de tradução do LE Kolibri. No Guia do LE Kolibri, fiz recomendações e comentários sobre o esboço do tópico e o plano de documentação propostos, além de outras coisas que precisam ser melhoradas. Para as diretrizes de tradução 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 notou durante a análise foi a concepção errada que existe entre documentos categorizados como Guia e Diretrizes.
Resultados
Fiz uma verificação de qualidade do Guia de tradução de LE, além das sugestões e dos comentários com um formulário preliminar que explico em mais detalhes na tarefa de auditoria de controle de qualidade. Estes são alguns comentários finais extraídos da avaliação: Links corrompidos para o site .js da sintaxe da ICU O formato usado para criar essas diretrizes está incorreto. O documento é um guia, não um guia. Tipografia inconsistente. Uso incorreto de cabeçalhos e títulos, Uso impróprio de linguagem e uso indevido de contrações. Uso impróprio de textos alternativos. Sobre declarações/ instruçõ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 do LE (comentários)
- Diretrizes de tradução LE com novos estilos e formato.
- Resumo dos tópicos
- Cronograma do projeto
- Tarefas de documentação