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:
- 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 com controle de versões de alta qualidade, consolidando grandes quantidades de informações de fontes distintas e reescrevendo informações para maior clareza, consistência e integridade.
- A documentação deve ser fácil de entender para iniciantes, sem patrocinar os usuários experientes em tecnologia.
- Criar um portal de documentação usando um gerador de sites estáticos
- 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.
- As informações são difíceis de encontrar e frequentemente duplicadas. É fácil se perder 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.
Como corrigir o problema:
Estrutura de documentação sugerida:
Página de destino
|-- Como começar
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (plataforma)
|-- Como usar a ScummVM
| |-- Tela de início
| |-- 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:
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 da ScummVM possa ser complexa em algumas plataformas, 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.
Como instalar a ScummVM:
Nos casos em que a instalação não é intuitiva ou o usuário não tem uma base técnica sólida, o usuário precisa de um guia completo para instalar a ScummVM em qualquer uma das plataformas com suporte.
Cada página de instalação abrangente deve abordar 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, adicionar e iniciar um jogo.
Como usar a 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 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 mais técnicas sobre as opções disponíveis para ajustar o desempenho dos jogos.
- Observações do jogo:
Qualquer informação específica de jogos que o usuário precise saber, incluindo, mas não se limitando a: - Quirks na instalação - Arquivos adicionais necessários - Controles diferentes ou incomuns
- Problemas conhecidos:
Esta seção precisa conter todos os bugs conhecidos específicos da versão.
- Notas da versão:
Embora nossa documentação tenha controle de versões, pode ser útil ter uma seção de notas da versão 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, já que essa é a maneira mais fácil de conseguir as informações que preciso de 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 da documentação atual, que podem ser verificadas quanto à integridade, precisão e moeda ou adicionadas conforme necessário.
Em seguida, analisarei a documentação existente: README, wiki e site. Conforme necessário, vou reescrever e adicionar cada seção conforme necessário e colocar todas as informações no novo portal. Também anotarei quais informações são extraídas de onde, para garantir que, quando o portal estiver ativo, não haverá duplicidades, contradições ou outras anomalias.
Em todo o processo, vou entrar em contato com os mentores, desenvolvedores, administradores de portas e outros especialistas no assunto para encontrar informações ausentes, 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, quero 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 esquecido.
Sugiro usar um guia de estilo, como o guia de estilo da documentação do desenvolvedor do Google, para garantir a consistência para esse conjunto de trabalho e para toda a documentação daqui para frente.
Sempre que possível, usarei capturas de tela, gifs e outros recursos visuais para aprimorar a compreensão.
Cronograma proposto:
Vínculo comunitário 17 de agosto a 13 de setembro de 2020
Continue conversando com os mentores e com a comunidade geral da 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.
- Preencher previamente os modelos com as informações existentes e distribuir para os desenvolvedores/administradores de portas 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
Usando o ScummVM: - A interface - Configurações globais Instalação da ScummVM: - Guias de instalação específicos da plataforma conforme os modelos concluídos são retornados para mim.
Semana 4 5 de outubro a 11 de outubro
Como usar o ScummVM: - Configurações do jogo - Atalhos do teclado Instalação do 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 - Controlar o mapeamento Instalação da ScummVM: - Guias de instalação específicos da plataforma à medida que os modelos completos são retornados para mim
Semana 6 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 conforme os modelos concluídos são retornados para mim
Semana 7 26 de outubro a 1o de novembro
Opções avançadas: - Gráficos - Áudio Instalação da ScummVM: - Guias de instalação específicos da plataforma conforme os modelos completos são devolvidos
Semana 8 De 2 de novembro 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 completos são retornados para mim
Semana 9 De 9 a 15 de novembro
Ajuda: - Informar um bug - Notas do jogo - Notas da versão
Como instalar o ScummVM: - Finalize os guias de 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 exibidos corretamente.
Semana 11 De 23 a 30 de novembro
- Finalize os itens pendentes e lance oficialmente o portal.
- Depois que o portal for lançado, remova as informações redundantes de outras fontes em consulta com os mentores.