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:
- Eletrônicos
- Redator técnico:
- Mister Gold
- Nome do projeto:
- Fluxo do tutorial do Electron
- Duração do projeto:
- Duração padrão (três meses)
Project description
RESUMO DO PROJETO
O Electron é uma das ferramentas mais conhecidas para criar apps de computador multiplataforma com JavaScript, HTML e CSS. Uma coleção de apps criados no Electron tem quase 900 entradas, e essa lista cresce continuamente. Algumas das ferramentas para desenvolvedores mais conhecidas, como Visual Studio Code, Atom, Postman, Slack e GitKraken, são criadas com base no Electron.
A popularidade do Electron está na curva de aprendizado simples e no baixo limite de entrada. Todos que conhecem JavaScript, HTML e CSS podem criar seu próprio aplicativo. As taxas de crescimento gerais enormes exigem a criação de tutoriais e guias de início fáceis de entender e usar.
O objetivo do projeto é dar confiança aos criadores de aplicativos que são novos no framework Electron e fornecer a eles uma experiência consistente e otimizada no desenvolvimento dos próprios aplicativos Electron desde o início.
Problemas do projeto
Confira a seguir uma lista dos problemas mais importantes relacionados à documentação dos tutoriais do Electron: 1. Ponto de partida pouco claro e informações de introdução não intuitivas sobre as etapas de desenvolvimento de apps 2. Informações dispersas e redundantes relacionadas ao processo de desenvolvimento de aplicativos 3. Peças desorganizadas de instruções do guia "Primeiros passos" sem uma única fonte de verdade
PROPOSTA DE PROJETO
De acordo com a meta do projeto e os problemas descritos acima, confira a seguir uma lista das melhorias propostas: 1. Atualize os guias. Para que as primeiras etapas sejam tranquilas e consistentes, os seguintes documentos precisam ser atualizados com uma mudança gradual do simples para o mais complexo: - Ambiente do desenvolvedor - Como criar seu primeiro app Electron - Como adicionar recursos ao seu app (criar uma página de resumo) - Embalagem e distribuição de apps 2. Reestruture o diretório de documentação. Para mostrar aos novos desenvolvedores o que é essencial para começar e o que pode ser considerado como etapas futuras, a página de documentos precisa ter uma divisão visual e contextual das etapas para que o primeiro aplicativo seja publicado o mais rápido possível. A reestruturação também inclui orientações sobre as próximas etapas possíveis. 3. Organizar e unificar a documentação de desenvolvimento de aplicativos. Todos os recursos devem ter um conjunto unificado de instruções sobre como instalá-lo/ativá-lo, como começar rapidamente, como trabalhar com um aplicativo após a primeira inicialização e como distribuí-lo. 4. Incluir o repositório electron-api-demos na documentação. O repositório Electron-api-demos contém alguns exemplos que mostram como adicionar atributos ao seu aplicativo Electron. Essas informações precisam ser incluídas no guia "Adicionar recursos ao seu app" para que a estratégia de conteúdo seja consistente com uma única fonte da verdade. 5. Integrar exemplos do Electron Fiddle à documentação. Essa etapa vai facilitar para os novos desenvolvedores entenderem como um código específico funciona sem precisar repetir as etapas manualmente. A integração inclui a criação de exemplos de código para os tutoriais atualizados e a adição do botão “Launch in Fiddle” aos blocos de código.
Minuto a minuto
Período de análise da inscrição: conheça a comunidade e as pessoas para trabalhar. Conheça os guias e as práticas recomendadas de contribuição para a comunidade. Faça as primeiras contribuições. Criar laços com a comunidade: explore a comunidade. Inspecione o estado atual da documentação do Electron. Identifique os pontos fracos. Semana 1: alinhar com os mentores os marcos e os resultados do projeto Semana 2: revisar as páginas "Ambiente do desenvolvedor" e "Escrever seu primeiro app Electron" Semana 3: revisar a arquitetura do aplicativo, adicionar recursos ao app, páginas de distribuição e empacotamento do app. Criar uma página de resumo com uma lista de recursos que podem ser adicionados ao app Semana 4: reestruturar o diretório de documentação Semana 5: preparar um modelo de como a Electron-api-demos será integrada à documentação principal Semanas 6 a 7: Migrar o repositório eletron-api-demos Semana 8: preparar um modelo de como o Electron Fiddle será integrado à documentação principal. Escreva a primeira amostra. Semanas 9 a 10: integrar o Electron Fiddle à documentação principal. Semana 11: finalizar a estrutura e as páginas da documentação principal após migrar o repositório electron-api-demos e os exemplos do Electron Fiddle. Semana 12: avaliar os resultados.
DETALHAMENTO DOS MARCOS
PERÍODO DE ANÁLISE DE INSCRIÇÕES A primeira parte do período será dedicada à verificação dos canais da comunidade e do código-fonte e ao contato com pessoas dedicadas ao projeto.
A segunda parte do período será dedicada a verificar a cultura de contribuição em geral, examinando guias de contribuição e práticas recomendadas. Esse será o momento das primeiras contribuições para ver como o fluxo funciona.
VINCULO COM A COMUNIDADE
Esse tempo será dedicado a uma análise mais detalhada da pasta de documentação e de seu roteiro. Com base nessas informações, será possível identificar pontos fracos (por exemplo, partes incompletas ou ausentes) que podem ser melhorados. Crie solicitações de envio (quando possível) para preencher as lacunas.
SEMANA 1 - SEMANA 2
A primeira semana será dedicada à comunicação com os mentores para alinhar os marcos esperados e a entrega deles no prazo.
A segunda semana será sobre revisar o ambiente do desenvolvedor e criar as páginas do seu primeiro aplicativo Electron. Para a página "Ambiente do desenvolvedor", ela vai incluir a revisão geral e a revisão ortográfica. Para a página “Como escrever seu primeiro aplicativo Electron”, isso incluirá a página como um guia passo a passo consistente, com pontos de início e fim claros, removendo informações redundantes (como dois blocos de código semelhantes nas seções “Desenvolvimento do Electron em resumo” e “Tentando este exemplo”).
Resultados: guias de introdução revisados e fáceis de seguir sobre como começar a usar aplicativos Electron.
SEMANA 3
Esta semana será dedicada a: 1. Melhorias na página "Arquitetura de aplicativos". Isso inclui: - a reescrita das informações existentes na seção "Processos principais e do renderizador" para torná-las simples e mais intuitivas para um leitor iniciante - adicionar representação visual da arquitetura, de como os processos são conectados, de como eles se comunicam e qual é a principal diferença entre eles. Exemplos de elementos visuais: Um, Dois, Três (baixa qualidade). 2. Unificação de informações sobre todos os recursos que você pode adicionar ao seu aplicativo Electron. Isso inclui reescrever os guias para que eles tenham um conjunto unificado de instruções sobre como instalar/ativar um recurso e um exemplo de como ele funciona. Além disso, uma nova página (resumo) com todos os recursos disponíveis para uso será criada. As instruções unificadas podem ter a seguinte aparência: - Visão geral - Exemplo: - Exemplo de código - Exemplo visual (quando possível)
- simplificação da página do Application Distribution. Isso inclui: a. Mesclar o empacotamento de aplicativos no guia "Distribuição de aplicativos" b. Dividir os métodos de distribuição em automáticos e manuais c. Usar o Electron Forge como um exemplo de distribuição automática d. Usar informações sobre o ASR da página "Empacote de aplicativos" e descrever a cópia de arquivos de origem e a criação de um arquivo ASR como exemplos de distribuição manual. #### SEMANA 4 Esta semana será dedicada à reestruturação do diretório de documentação. It includes:
1 - Dividindo os guias em pelo menos três categorias: a. Guia de início rápido b. Aprender os conceitos básicos c. Etapas avançadas
A categoria "Guia de início rápido" vai conter os tutoriais básicos (instalação, configuração, distribuição) para criar uma série consistente de guias que permitam que os novatos comecem do zero. Cada guia deve conter links para guias anteriores e próximos da série.
A estrutura pode ter a seguinte aparência: 1. Pré-requisitos 2. Instale o Electron. Criar um aplicativo básico 4. Empacotar/distribuir o aplicativo
Depois de concluir a seção "Início rápido", o usuário vai saber o básico sobre como os aplicativos Electron funcionam e vai ter um aplicativo Electron totalmente funcional e distribuível.
A categoria Noções básicas contém guias que visam reforçar o conhecimento sobre o Electron e ampliar a inscrição criada nas seções de início rápido. Esses guias incluem: - Arquitetura do aplicativo - Como adicionar recursos ao seu app - Modelos e CLIs
A categoria "Etapas avançadas" vai conter guias mais avançados para configurar e ajustar seu aplicativo Electron: - Testes e depuração - Acessibilidade - Segurança - Atualizações
2 - Reduzir o número de páginas de documentação. A versão atual da documentação contém um certo grau de conteúdo sobreposto e instruções não categorizadas. Por exemplo: - Instalação e instalação do Electron ao criar seu primeiro app - Empacotamento e empacotamento de aplicativos em um arquivo no Application Distribution - Instruções não categorizadas nas categorias "Detalhes" e "Avançado": Sugestão: mova os documentos a seguir para o GitHub e exclua da documentação principal. Esses documentos são específicos para as diretrizes de desenvolvimento do Electron, e o repositório de origem é o primeiro lugar para procurá-los: - Como desenvolver o Electron - Desenvolvimento do Chromium - Desenvolvimento do V8 - Problemas no Electron - Patches no Electron - Solicitações de mesclagem - Estrutura do diretório do código-fonte - Testes - Estilo de programação
A ideia principal da redução é se livrar de um número excessivo de guias disponíveis, juntando as peças do quebra-cabeça de informações e oferecendo aos novatos uma versão mais estruturada, fácil de navegar e fácil de usar da documentação do Electron.
SEMANAS 5 a 7
A semana 5 será dedicada à preparação de um modelo (uma maneira) de como as demonstrações da API da Electron serão integradas à documentação principal. Este modelo pode ter a seguinte aparência: 1. Na documentação principal, em "Adicionar recursos ao seu app", crie as categorias representadas no electron-api-demos 2. Ao passar por cada uma das categorias, transfira os exemplos de demonstração para a documentação principal: - Os exemplos de código podem ser retirados do código-fonte ou da descrição do recurso correspondente no aplicativo - Cada exemplo transferido precisa ser seguido pela descrição associada - Cada exemplo filho (por exemplo, a caixa de diálogo de erro como filho das caixas de diálogo do sistema de uso) precisa ser transferido para o pai
OBSERVAÇÃO 1: há exemplos nas demonstrações da API do Electron e na documentação principal (por exemplo, atalhos de teclado, arrastar e soltar). Nesse caso, o exemplo de electron-api-demos tem prioridade, e o exemplo na documentação principal precisa ser ignorado.
OBSERVAÇÃO 2: muitos exemplos no aplicativo electron-api-demos têm uma prévia da demonstração ao vivo do recurso ou da funcionalidade descrita. Essa funcionalidade será ignorada até a integração do Electron Fiddle nas semanas 9 e 10.
- Atualize a página que lista todos os recursos disponíveis para uso (criado durante a Semana 3) respeitando a nova hierarquia de exemplos.
As semanas 6 e 7 serão dedicadas à transferência de exemplos de electron-api-demos para a documentação principal, de acordo com o modelo descrito acima. Como etapa final, o repositório electron-api-demos precisa ser excluído ou descontinuado.
SEMANAS 8 a 10
A Semana 8 será dedicada à preparação de um modelo (uma maneira) de como o Electron Fiddle será integrado à documentação principal. Essa iniciativa já foi lançada (confira os detalhes no problema no 20442) pela Electron junto com voluntários da comunidade, mas ela precisa de uma finalização adequada.
Para continuar com as amostras do Fiddle, o modelo básico pode ser parecido com este: 1. Escolha um exemplo da documentação principal (por exemplo, o guia de início rápido). Nesse ponto, a documentação também precisa conter exemplos de electron-api-demos. 2. Recriar o exemplo no Electron Fiddle (usando o código de exemplo ou o código-fonte como ponto de partida); 3. Salve o Fiddle localmente em uma pasta. 4. Mova o exemplo para /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * A lista de exemplos concluídos é descrita na seção "Lista de demonstrações" do problema. 5. Adicionamos o botão "Launch in Fiddle", conforme descrito no comentário inicial do problema #2848.
As semanas 9 e 10 serão dedicadas à integração de exemplos de electron-api-demos (que já foram convertidos em Fiddles) à documentação principal, de acordo com o modelo descrito acima.
SEMANA 11
Esta semana será totalmente dedicada à finalização do projeto de escrita após a migração bem-sucedida do repositório electron-api-demos e dos exemplos do Electron Fiddle. Isso inclui: - verificar se todos os exemplos de código atuais têm o botão "Launch in Fiddle" - verificar se todos os exemplos de código atuais estão funcionando corretamente como Fiddles - verificar se a documentação principal não se refere mais ao repositório electron-api-demos
SEMANA 12
Finalização do trabalho concluído. Verificações de aceitação.