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:
- ScummVM
- Redator técnico:
- Cadi
- Nome do projeto:
- Abrir um portal de documentação
- Duração do projeto:
- Duração padrão (três meses)
Project description
Objetivos:
- Para produzir documentação de usuário final com controle de versão e de alta qualidade, consolidando grandes quantidades de informações de fontes distintas e reescrevendo as informações para clareza, consistência e integridade.
- A documentação deve ser fácil de entender para iniciantes, sem que usuários entusiasmados com tecnologia.
- Criar um portal de documentação usando um gerador de site estático.
- Para preparar a documentação do usuário final para o futuro, criando modelos e instruções detalhadas de instruções para futuros colaboradores de código aberto.
A situação atual:
- A documentação disponível do ScummVM está distribuída por várias fontes.
- As informações são difíceis de encontrar e muitas vezes duplicadas. É fácil se perder em páginas obscuras.
- É difícil saber quais informações são atuais e quais estão desatualizadas.
- Algumas informações estão ausentes ou incompletas.
Corrigindo o problema:
Estrutura de documentação sugerida:
Página de destino
|-- Introdução
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (plataforma)
|-- Como usar o ScummVM
| |-- O inicializador
| |-- Configurações globais
| |-- Configurações do jogo
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- Música e som
|-- Ajuda
| |-- Perguntas frequentes
| |-- Contatos
| |-- Problemas conhecidos
| -- Reporting a bug
|-- Game Notes-- Notas da versão
- Primeiros passos:
Os novos usuários geralmente procuram um guia de início rápido para começar o mais rápido possível. Embora a instalação do ScummVM possa ser complexa em algumas plataformas, não é o caso de computadores.
O guia de início rápido precisa abordar o seguinte:
- Como instalar o ScummVM no Windows, Mac e Linux.
Como carregar, adicionar e iniciar um jogo.
Como instalar o ScummVM:
Nos casos em que a instalação não é intuitiva ou quando o usuário não tem uma base técnica sólida, ele precisa de um guia abrangente para instalar o ScummVM em qualquer uma das plataformas compatíveis.
Cada página de instalação abrangente precisa incluir o seguinte:
- Quaisquer requisitos/pré-requisitos do sistema.
- Como fazer o download da versão adequada do ScummVM.
- Como instalar o ScummVM.
- Como carregar jogos na plataforma escolhida, especialmente quando ela não é a plataforma para a qual o jogo foi projetado.
Como iniciar o ScummVM, adicionar um jogo e iniciar um jogo.
Como usar o ScummVM:
Os usuários precisam de documentos de referência que expliquem como usar o ScummVM.
Os documentos de referência precisam abranger o seguinte:
- A interface do Iniciador: como cada janela e guia se parece e como elas funcionam.
- Uma explicação das configurações disponíveis, globais e específicas do jogo.
Atalhos de teclado.
Opções avançadas:
Os usuários avançados precisam de informações adicionais e mais técnicas sobre as opções disponíveis para ajustar o funcionamento dos jogos.
- Notas do jogo:
Qualquer informação específica do jogo que o usuário precisa saber, incluindo, entre outros: - peculiaridades da instalação - arquivos adicionais necessários - controles diferentes ou incomuns
- Problemas conhecidos:
Essa seção deve conter todos os bugs conhecidos específicos da versão.
- Notas da versão:
Embora nossa documentação seja versionada, ter uma seção de notas de lançamento pode ser útil para fornecer um resumo das mudanças na versão mais recente. Isso pode incluir algumas áreas que estão fora do escopo desta documentação, como jogos com suporte recente ou informações sobre novos mecanismos.
Plano de ataque:
Proponho começar criando um modelo para as páginas de instalação do ScummVM, porque essa é a maneira mais fácil de conseguir as informações que preciso dos mantenedores/desenvolvedores de porta (especialmente quando essas informações são escassas ou inexistentes). Preencherei com as informações que já tenho da documentação atual, que podem ser verificadas quanto à integridade, precisão e moeda ou adicionadas conforme necessário.
Em seguida, vou analisar a documentação existente: README, wiki e site. Conforme prossegui, vou reescrever e adicionar a cada seção conforme necessário e colocar todas as informações no novo portal. Também vou anotar de onde as informações são extraídas para garantir que, quando o portal estiver ativo, não haja duplicação, contradições ou outras anomalias.
Durante o processo, vou entrar em contato com os mentores, desenvolvedores, mantenedores de porta e outros especialistas em matéria para encontrar informações ausentes e garantir que cada página esteja atualizada e abrangente.
No espírito de colaboração e sujeito à aprovação dos mentores, eu gostaria que o portal do trabalho em andamento ficasse acessível à comunidade do ScummVM durante o processo de escrita, para receber feedback em tempo real e garantir que nada seja perdido ao longo do processo.
Sugiro usar um guia de estilo, como o guia de estilo da documentação para desenvolvedores do Google, para garantir a consistência desse trabalho e de toda a documentação daqui para frente.
Sempre que possível, vou usar capturas de tela, GIFs e outros recursos visuais para facilitar a compreensão.
Cronograma proposto:
Interação com a comunidade 17 de agosto a 13 de setembro de 2020
Continue conversando com os mentores e a comunidade do ScummVM para ajustar a visão do projeto e finalizar detalhes, como a estrutura e o conteúdo do documento.
Semana 1 14 a 20 de setembro
- Crie um modelo para as páginas de instalação específicas da plataforma.
- Preencha automaticamente os modelos com as informações atuais e distribua-os aos mantenedores/desenvolvedores de portas apropriados para mais informações.
Semana 2 21 a 27 de setembro
- Configurar o novo portal de documentação.
Semana 3 28 de setembro a 4 de outubro
Como usar o ScummVM: - A interface - Configurações globais Instalação do ScummVM: - Guias de instalação específicos da plataforma, conforme os modelos concluídos são retornados para mim.
Semana 4 5 a 11 de outubro
Como usar o ScummVM: - Configurações do jogo - Atalhos do teclado Como instalar o ScummVM: - Guias de instalação específicos da plataforma conforme os modelos completos são devolvidos para mim
Semana 5 12 a 18 de outubro
Opções avançadas: - Nuvem e LAN - Mapeamento de controle Instalação do ScummVM: - Guias de instalação específicos da plataforma à medida que modelos completos são devolvidos para mim
Semana 6 19 a 25 de outubro
Opções avançadas: - Configuração - Opções de linha de comando Instalação do ScummVM: - Guias de instalação específicos da plataforma, porque os modelos concluídos são retornados para mim
Semana 7 De 26 de outubro a 1o de novembro
Opções avançadas: - Gráficos - Áudio Instalação do ScummVM: - Guias de instalação específicos da plataforma, já que os modelos concluídos são retornados para mim
Semana 8 De 2 a 8 de novembro
Ajuda: - Perguntas frequentes - Contatos - Problemas conhecidos
Instalação do ScummVM: - Guias de instalação específicos da plataforma, como modelos concluídos, são retornados para mim
Semana 9 9 a 15 de novembro
Ajuda: - Como denunciar um bug - Notas do jogo - Notas da versão
Instalação do ScummVM: - Finalize todos os guias de plataforma ainda não concluídos.
Semana 10 16 a 22 de novembro
- Edição final, revisão e finalização de todas as decisões relacionadas ao portal, como navegação na barra lateral, ajustes de tema/CSS etc.
- Verifique se todos os links funcionam conforme o esperado.
- Verifique se as imagens/gifs aparecem corretamente.
Semana 11 De 23 a 30 de novembro
- Finalize todos os itens pendentes e lance o portal oficialmente.
- Depois que o portal for lançado, remova informações redundantes de outras fontes em consulta com os mentores.