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:
- ScummVM
- Redator técnico:
- Cadi
- Nome do projeto:
- Lançar um portal de documentação
- Duração do projeto:
- Duração padrão (3 meses)
Project description
Objetivos:
- Produzir documentação do usuário final de alta qualidade com controle de versão consolidando grandes quantidades de informações de fontes diferentes e reescrevendo informações para maior clareza, consistência e integridade.
- A documentação deve ser de fácil compreensão para iniciantes, sem ser patronoso para usuários com experiência em tecnologia.
- Criar um portal de documentação usando um gerador de site estático
- Preparar a documentação do usuário final para o futuro criando modelos e instruções detalhadas para futuros colaboradores de código aberto.
Situação atual:
- A documentação do ScummVM disponível está espalhada por várias fontes.
- Informações são difíceis de encontrar e frequentemente duplicadas, além de se perderem em páginas obscuras.
- É difícil saber quais informações estão atualizadas e quais estão desatualizadas.
- Algumas informações estão ausentes ou incompletas.
Correção do problema:
Estrutura de documentação sugerida:
Página de destino
|-- Getting Started
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (platform)
|-- Como usar a ScummVM
| |-- O acesso rápido
| |-- 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
|-- Notas da versão
| -- Reporting a bug
|-- Game Notes-- Notas da versão
- Primeiros passos:
Novos usuários geralmente procuram um guia de início rápido para começar o mais rápido possível. A instalação da ScummVM pode ser complexa em algumas plataformas, mas a instalação em um computador não é.
O guia de início rápido deve abordar o seguinte:
- Como instalar a ScummVM no Windows, Mac e Linux.
Como carregar, adicionar e iniciar um jogo.
Para instalar o ScummVM:
Nos casos em que a instalação não é intuitiva ou o usuário não tem uma base técnica sólida, ele precisa de um guia completo para instalar a ScummVM em qualquer uma das plataformas com suporte.
Cada página de instalação abrangente deve cobrir o seguinte:
- Quaisquer requisitos/pré-requisitos do sistema
- Como fazer o download da versão apropriada do ScummVM.
- Como instalar a ScummVM.
- Como carregar jogos na plataforma escolhida, principalmente quando não é a plataforma para a qual o jogo foi projetado.
Como iniciar a ScummVM e adicionar ou 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 abordar o seguinte:
- A interface da tela de início; a aparência de cada janela e guia e como elas funcionam.
- Uma explicação das configurações disponíveis, tanto globais quanto específicas do jogo.
Atalhos do teclado/teclas de atalho.
Opções avançadas:
Os usuários avançados precisam de informações adicionais e técnicas sobre as opções disponíveis para ajustar o desempenho dos jogos.
- Observações do jogo:
Qualquer informação específica do jogo que o usuário precise saber, incluindo, mas não se limitando a: - Quirks da instalação - Qualquer arquivo adicional necessário - Controles incomuns ou diferentes
- Problemas conhecidos:
Esta seção deve conter todos os bugs conhecidos específicos da versão.
- Notas da versão:
Nossa documentação terá controle de versões, mas ter uma seção "Notas da versão" 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:
Sugiro 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 portas (especialmente quando essas informações são escassas ou não existem). Vou preencher automaticamente todas as informações que já tenho na documentação, que podem ser verificadas quanto à integridade, precisão e moeda ou adicionadas conforme necessário.
Em seguida, vasculharei a documentação existente; README, wiki e o site. Conforme necessário, vou reescrever e adicionar a cada seção conforme necessário e colocar todas as informações no novo portal. Também vou anotar quais informações são extraídas de onde o portal é ativado, para garantir que, quando o portal estiver ativo, não haverá informações duplicadas, contradições ou outras anomalias.
Durante todo o processo, vou entrar em contato com os mentores, os desenvolvedores, os mantenedores de portas e outros especialistas no assunto para encontrar as informações que estão faltando, além de garantir que cada página seja a mais atualizada e abrangente possível.
Para colaborar e estar sujeito à aprovação dos mentores, gostaria de disponibilizar o portal de trabalho em andamento para a comunidade da ScummVM durante todo 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 do desenvolvedor do Google, para garantir a consistência desse corpo de trabalho e de toda a documentação no futuro.
Sempre que possível, usarei capturas de tela, gifs e outros recursos visuais para aprimorar o entendimento.
Cronograma proposto:
Vínculo comunitário 17 de agosto a 13 de setembro de 2020
Continue conversando com os mentores e com a comunidade da ScummVM para ajustar a visão do projeto e finalizar detalhes, como a estrutura e o conteúdo dos documentos.
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 existentes e distribua para os mantenedores/desenvolvedores de portas apropriados.
Semana 2 De 21 a 27 de setembro
- Configure o novo portal de documentação.
Semana 3 De 28 de setembro a 4 de outubro
Usando o ScummVM: - A interface - Configurações globais Instalação do ScummVM: - Guias de instalação específicos da plataforma à medida que os modelos completos são retornados para mim.
Semana 4 5 de outubro a 11 de outubro
Usando o ScummVM: - Configurações do jogo - Atalhos do teclado Instalação do ScummVM: - Guias de instalação específicos da plataforma à medida que os modelos completos são retornados para mim
Semana 5 12 a 18 de outubro
Opções avançadas: - Nuvem e LAN - Controle de mapeamento Instalação do ScummVM: - Guias de instalação específicos da plataforma à medida que os modelos completos são retornados para mim
Semana 6 De 19 a 25 de outubro
Opções avançadas: - Configuração - Opções da linha de comando Instalação do ScummVM: - Guias de instalação específicos da plataforma à medida que 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 Como instalar a ScummVM: - Guias de instalação específicos da plataforma à medida que os modelos completos são retornados para mim
Semana 8 De 2 a 8 de novembro
Ajuda: - Perguntas frequentes - Contatos - Problemas conhecidos
Como instalar o ScummVM: - Guias de instalação específicos da plataforma à medida que os modelos concluídos são retornados para mim
Semana 9 De 9 a 15 de novembro
Ajuda: - Informar um bug - Notas do jogo - Notas da versão
Instalação do ScummVM: - Finalize todos os guias da plataforma ainda não concluídos.
Semana 10 De 16 a 22 de novembro
- Edição, 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 como esperado.
- Verifique se as imagens/gifs são exibidas corretamente.
Semana 11 De 23 a 30 de novembro
- Finalize todos os itens pendentes e abra oficialmente o portal!
- Depois que o portal for lançado, remova as informações redundantes de outras fontes consultando os mentores.