Projeto Elétron

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:

Elétron

Redator técnico:

Mister Gold

Nome do projeto:

Fluxo do tutorial do Electron

Duração do projeto:

Duração padrão (3 meses)

Project description

RESUMO DO PROJETO

O Electron é uma das ferramentas mais populares para criar aplicativos de desktop multiplataforma com JavaScript, HTML e CSS. Um conjunto de apps criados no Electron tem quase 900 entradas, e essa lista cresce continuamente. Algumas das ferramentas de desenvolvedor mais conhecidas, como Visual Studio Code, Atom, Postman, Slack e GitKraken, são criadas no Electron.

A popularidade do Electron está na curva de aprendizado simples e no baixo limite de entrada. Todos que conhecem JavaScript, HTML e pilha de CSS podem criar o próprio aplicativo. Altas taxas gerais de crescimento ditam a necessidade de criar tutoriais e guias de iniciação fáceis de entender e usar.

O objetivo do projeto é trazer confiança aos criadores de aplicativos que são novos no framework Electron e fornecer a eles uma experiência consistente e simplificada no desenvolvimento de seus próprios aplicativos Electron desde o início.

Problemas do projeto

Veja 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 aplicativos 2. Informações dispersas e redundantes relacionadas ao processo de desenvolvimento de aplicativos 3. Partes desorganizadas das instruções do guia de “primeiros passos” sem uma única fonte de verdade

PROPOSTA DO PROJETO

De acordo com o objetivo do projeto e os problemas descritos acima, veja a seguir uma lista das melhorias propostas: 1. Atualize os guias. Para que as primeiras etapas sejam tranquilas e consistentes, os documentos a seguir devem ser atualizados com uma mudança gradual do simples para o mais complexo: - Ambiente do desenvolvedor - Como escrever seu primeiro app Electron - Como adicionar recursos ao seu app (criar uma página de resumo) - Empacotamento e distribuição do app 2. Reestruturar o diretório de documentação. Para mostrar aos novos desenvolvedores o que é essencial para começar e o que pode ser considerado como uma etapa futura, a página de documentos deve ter divisão visual e contextual das etapas para ativar o primeiro aplicativo o mais rápido possível. A reestruturação também inclui orientações sobre as possíveis próximas etapas. 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 app após o primeiro lançamento e como distribuí-lo. 4. Inclua o repositório electron-api-demos na documentação. O repositório electron-api-demos contém um conjunto de exemplos que mostram como adicionar atributos ao seu aplicativo Electron. Essas informações devem ser incluídas no guia "Como adicionar recursos ao seu app" para manter a consistência com uma estratégia de conteúdo de fonte única de verdade. 5. Integrar exemplos de violino eletrônico à documentação. Essa etapa vai facilitar para os novos desenvolvedores a visualização de como uma parte específica do código funciona, sem a necessidade de 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 com quem trabalhar. Conheça os guias e as práticas recomendadas de contribuição da comunidade. Faça as primeiras contribuições. Vínculo comunitário - Explore a comunidade. Inspecione o estado atual da documentação do Electron. Identifique pontos fracos. Semana 1: alinhar com os mentores sobre os marcos e os resultados do projeto Semana 2: revisar o ambiente do desenvolvedor e criar suas primeiras páginas do app Electron Semana 3: revisar a arquitetura do aplicativo, adicionar recursos ao app, empacotamento e páginas de distribuição 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 o electron-api-demos será integrado à documentação principal Semanas 6 a 7: migração do repositório electron-api-demos Semana 8: preparação de um modelo de como o Electron Fiddle será integrado à documentação principal Escreva a primeira amostra. Semanas 9 a 10: integrar o violino de elétron à documentação principal Semana 11: finalização da estrutura e das páginas da documentação principal após a migração do repositório electron-api-demos e das amostras do violino eletrônico Semana 12: avaliação dos resultados

ANÁLISE DETALHADA DOS MARCOS

PERÍODO DE ANÁLISE DE INSCRIÇÃO A primeira parte do período será dedicada a verificar os canais da comunidade e o código-fonte, além de entrar em contato com pessoas dedicadas ao projeto.

A segunda parte do período será dedicada à verificação da cultura de contribuição em geral, examinando os guias de contribuição e as práticas recomendadas. Este será o momento das primeiras contribuições para ver como o fluxo funciona.

VINCULAÇÃO DA COMUNIDADE

Este tempo será dedicado a um exame mais detalhado da pasta de documentação, junto com o roteiro dela. 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, com o objetivo de alinhar os marcos esperados e a entrega pontual.

A segunda semana será sobre como revisar o ambiente de desenvolvedores e escrever seu primeiro app eletrônico. Na página "Ambiente do desenvolvedor", isso vai incluir a reescrita da visão geral e da revisão. Para a página "Como criar seu primeiro aplicativo Electron", é necessário torná-la 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 na seção “Desenvolvimento de elétrons” e “Como testar este exemplo”).

Resultados: guias de introdução revisados e fáceis de seguir sobre como usar os aplicativos Electron de início rápido.

SEMANA 3

Esta semana será dedicada a: 1. Melhorias na página "Arquitetura de aplicativos". Isso inclui: - reescrever as informações existentes na seção "Principais processos" e "Processos do renderizador" para torná-las mais simples e intuitivas para os leitores iniciantes - adicionar uma representação visual da arquitetura, como os processos estão conectados, como eles se comunicam e a principal diferença entre eles. Exemplos de recursos 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 tenham um conjunto unificado de instruções sobre como instalar/ativar um recurso, além de um exemplo de como o recurso funciona. Além disso, uma nova página (resumo) com todos os recursos disponíveis será criada. As instruções unificadas podem ter esta aparência: - Visão geral - Exemplo: - Exemplo de código - Exemplo visual (quando possível)

1. simplificação da página "Distribuição de aplicativos". Isso inclui: a. Combinar o Empacotamento de aplicativos no guia de Distribuição de aplicativos b. dividir os métodos de distribuição em automático e manual c. Tomar a eletron-forge como um exemplo de distribuição automática d. Obter informações sobre asar da página “Empacotamento de aplicativos” e descrever a cópia de arquivos de origem e a criação de um arquivo asar como exemplos de distribuição manual. #### SEMANA 4 Esta semana será dedicada à reestruturação do diretório de documentação. Saiba o que ele inclui:

1 - dividindo os guias existentes em pelo menos três categorias: a. Guia de início rápido b. Aprendizado básico c. Etapas avançadas

A categoria "Guia de início rápido" contém os tutoriais básicos (instalação, configuração, distribuição) para criar uma série consistente de guias, que permitirá que os novatos usem o guia de início rápido do zero. Cada guia deve conter links para os guias anterior e seguinte da série.

A estrutura pode ser a seguinte: 1. Pré-requisitos 2. Instale o Electron 3. Criar um aplicativo básico 4. Empacotar/distribuir o aplicativo

Depois de concluir a seção "Guia de início rápido", o usuário saberá as noções básicas de como os aplicativos Electron funcionam e terá um aplicativo Electron distribuível totalmente funcional.

A categoria "Aprendizado básico" contém os guias que visam fortalecer o conhecimento sobre o Electron e ampliar o aplicativo criado nas seções de início rápido. Esses guias incluem: - Arquitetura do aplicativo - Como adicionar recursos ao app - Boilerplats e CLIs

A categoria "Etapas avançadas" contém guias mais avançados para configurar e ajustar seu aplicativo Electron: - Teste 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 sem classificação. Por exemplo: - Instalação e instalação do Electron na gravação do seu primeiro app - Empacotamento de aplicativos e empacotar seu app em um arquivo no Application Distribution - Instruções sem classificação nas categorias "Detalhado" 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 diretrizes de desenvolvimento do Electron, e o repositório de origem é o primeiro lugar para procurá-los: - Desenvolvimento do Electron - Desenvolvimento do Chromium - Desenvolvimento V8 - Problemas no Electron - Patches no Electron - Solicitações de extração - Estrutura de diretório do código-fonte - Teste - Estilo de codificação

A ideia principal da redução é eliminar o grande número de guias disponíveis, unir as informações espalhadas do quebra-cabeça e oferecer aos iniciantes uma versão da documentação do Electron mais estruturada, fácil de navegar e fácil de usar.

SEMANAS 5 - 7

A semana 5 será dedicada à preparação de um modelo (uma forma) de como o ectron-api-demos será integrado à documentação principal. Esse modelo pode ter a seguinte aparência: 1. Na documentação principal, em "Como adicionar recursos ao seu app", crie as categorias representadas em electron-api-demos. 2. Percorrendo cada uma das categorias, transfira os exemplos de demonstração para a documentação principal: - As amostras de código podem ser extraídas do código-fonte ou da descrição do recurso correspondente no aplicativo - Cada exemplo transferido deve ser seguido pela descrição associada - Cada exemplo filho (por exemplo, a caixa de diálogo "Erro" como filho das caixas de diálogo "Usar sistema") deve ser transferido pela própria

OBSERVAÇÃO n.o 1: há exemplos que existem tanto no electron-api-demos quanto na documentação principal (por exemplo, atalhos de teclado, arrastar e soltar). Nesse caso, o exemplo de electron-api-demos deve ter prioridade, e o exemplo na documentação principal deve ser ignorado.

OBSERVAÇÃO 2: muitos exemplos no aplicativo electron-api-demos apresentam uma visualização de demonstração ao vivo do recurso ou funcionalidade descrita. Esta funcionalidade será ignorada até a integração do Electron Fiddle nas semanas 9 a 10.

1. Atualize a página que lista todos os recursos disponíveis para uso (que foram criados 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. Na etapa final, exclua ou suspenda o uso do repositório electron-api-demos.

SEMANAS 8 A 10

A semana 8 será dedicada à preparação de um modelo (uma forma) de integração do violino eletrônico à documentação principal. Essa iniciativa já foi lançada (confira os detalhes no exemplar 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 ter a seguinte aparência: 1. Escolha um exemplo na documentação principal, como no guia de início rápido. Neste ponto, a documentação também precisa conter exemplos de electron-api-demos. 2. Recrie 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 está descrita na seção "Lista de demonstrações" do problema. 5. Adicione 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 do ectron-api-demos (que já foram convertidos em Fiddles) à documentação principal de acordo com o modelo descrito acima.

SEMANA 11

Esta semana, vamos dedicar totalmente à finalização do projeto de escrita após a migração do repositório electron-api-demos e das amostras do Electron Fiddle. Isso inclui: - verificar se todos os exemplos de código existentes têm o botão “Launch in Fiddle” - verificar se todos os exemplos de código existentes 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.