Esta página foi traduzida pela API Cloud Translation.

Projeto ESLint

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:: ESLint
Redator técnico:: Khawar
Nome do projeto:: Reorganizar/reescrever a documentação de configuração
Duração do projeto:: Duração padrão (3 meses)

Project description

Com abstração

O objetivo deste projeto é reestruturar a documentação de configuração do ESLint e criar uma arquitetura da informação eficaz. Isso facilita a navegação e também melhora a usabilidade e a utilidade da documentação.

Resumo do projeto A documentação de configuração do ESLint (https://eslint.org/docs/user-guide/configuration), no estado atual, fornece muitas informações em uma única página. Apesar da presença de títulos, subtítulos e parágrafos apropriados na página, a documentação pode ficar sobrecarregada. Não há como navegar para uma seção específica da página, o que é frustrante para um usuário interessado em uma seção específica. Por causa dessa falta de organização, as informações também podem se perder, deixando de cumprir sua finalidade e pedindo mais esforços.

No entanto, esses problemas podem ser resolvidos com várias etapas cuidadosas. Proponho uma auditoria de conteúdo como a primeira etapa nessa reorganização. Uma auditoria de conteúdo não só ajuda a identificar os problemas na apresentação das informações, como também destaca as deficiências do conteúdo em si (por exemplo, informações desatualizadas ou incompletas). Depois, pretendo criar a arquitetura da informação (AI) para revelar a rede de conhecimento. Isso nos permitirá agrupar as informações de acordo com diversos tópicos e encontrar links entre vários tópicos intimamente relacionados. Os insights obtidos com essas duas práticas serão usados para dividir a documentação de uma única página em várias páginas. O pacote inteiro pode ser vinculado e cruzado com referências no Markdown. Como resultado, haverá uma versão mais organizada da documentação de configuração, uma versão mais fácil de navegar e entender.

Motivação Apesar de eu usar software de código aberto há algum tempo, minha familiaridade com o termo é bastante nova, parecida com meu conhecimento sobre software Lint. Quando comecei a aprender Python (através do edX), me perguntei como pequenos erros podem bagunçar todo o código. Pensei que seria bom ter seus códigos testados de alguma forma e identificar os erros, e então descobri o termo "inspeção". Ainda não usei um software de inspeção, mas tenho certeza de que eles tornarão minha vida muito mais fácil nos próximos dias.

Com minha formação em engenharia elétrica e alguma experiência em programação, consigo entender os problemas de codificação e os requisitos dos programadores de uma maneira melhor. Além disso, minha graduação em Comunicação Técnica e Profissional me torna uma defensora dos usuários, tentando facilitar a vida das pessoas. Minhas habilidades e experiência vão servir como uma boa combinação para este projeto, agregando valor à documentação do ESLint.

Objetivos O objetivo geral deste projeto é garantir que a documentação na página de configuração do ESLint seja fácil de entender e não sobrecarregue os usuários. É importante para o sucesso do projeto que a navegação pelo conteúdo seja fácil e sem complicações. Os objetivos importantes do projeto são os seguintes. - Realizar uma auditoria abrangente do conteúdo - Criar uma arquitetura de informações para entender o fluxo de informações - Melhorar a arquitetura da informação para reorganizar a documentação - Identificar links e referências entre diferentes seções do conteúdo - Reescrever/editar partes da documentação, se necessário para atender aos requisitos de reconfiguração

- Garantir que o conteúdo seja flexível e reutilizável

A configuração da descrição do projeto do ESLint é um recurso importante, que torna o ESLint personalizável. Os usuários com interesse em configuração certamente vão se interessar por um ou dois aspectos. É importante, portanto, que o usuário seja orientado ao tópico de interesse específico, fornecendo a solução de forma eficiente. O estado atual da documentação de configuração do ESLint contém muitas informações úteis, mas é organizado de forma a fazer com que os usuários se sintam sobrecarregados, frustrados e perdidos. Por exemplo, se alguém estiver interessado em aprender sobre o uso de plug-ins de terceiros no ESLint, será necessário rolar para baixo a discussão sobre como especificar analisadores, ambientes e globais. Toda a prática é cansativa para os usuários e pode afastá-los do site. Da mesma forma, se um usuário estiver em algum lugar no meio da página e quiser ir para uma seção específica ou apenas ver tópicos semelhantes, isso não será uma tarefa fácil para ele, pois nenhum tipo de auxílio é fornecido a eles. Essas questões precisam de atenção imediata, pois a qualidade de qualquer documentação, não importa quão bem redigida, depende de sua utilidade. Proponho soluções para esses e outros problemas relacionados na discussão que segue.

Auditoria de conteúdo O primeiro passo no processo de reorganizar a documentação de configuração é realizar uma auditoria abrangente do conteúdo. O objetivo da auditoria é identificar alguns problemas importantes, como conteúdo desatualizado, duplicação, falta de conteúdo etc. Uma planilha de auditoria de conteúdo criada como resultado será compartilhada com as equipes de gerenciamento e documentação para feedback. Isso ajudará a elaborar uma nova estratégia para estruturar e apresentar a documentação.

Criação da arquitetura da informação Para entender a rede de conhecimento ou o fluxo de informações na documentação de configuração, a criação de arquitetura da informação (AI) pode ser valiosa. Os resultados da auditoria de conteúdo servirão como uma boa base para entender e desenvolver o fluxo de informações. Uma versão aprimorada da AI será, então, criada para organizar e apresentar a documentação de uma maneira melhor. Essa AI aprimorada não apenas reestruturará o conteúdo atual, mas também identificará links e bifurcações entre várias seções da documentação, criando assim uma rede eficiente. Por exemplo, o conteúdo em "Como configurar regras" pode ser seguido por um link que leva a "Desativar regras com comentários inline". Outros links desse tipo também podem ser identificados, criando relações entre diferentes seções da documentação.

Uma auditoria de conteúdo e AI fornecerão informações adequadas para criar um sumário detalhado com links que levam a seções e subseções específicas da documentação. Criar arquivos separados para cada seção e adicionar referências apropriadas a outras seções pode agregar valor a todo o conjunto de documentos. É possível criar um sumário para os usuários que acessam a documentação de configuração, o que ajuda na jornada deles no site. O sumário pode incluir todos os títulos de primeiro e segundo nível para mantê-lo breve e abrangente. Uma dessas práticas, por exemplo, é a usada pelo Prettier (https://prettier.io/docs/en/index.html) para organizar a documentação.

Toda a documentação será criada usando Markdown para manter as coisas simples e bem organizadas. Vamos tomar cuidado para garantir que a documentação possa ser reutilizada, porque pode crescer e mudar no futuro.

Ferramentas para usar Algumas ferramentas importantes que podem ser úteis ao trabalhar no projeto são - Draw.io para criar ilustrações para AI conforme necessário - Atom (ou editor semelhante) para escrever e editar documentos no Markdown

- GitHub para garantir o controle de versões da documentação

Marcos Do envio da proposta à conclusão do projeto, os marcos provisórios a seguir vão garantir que ele seja concluído no prazo, mantendo o fluxo certo no processo.

10 de julho de 2020 a 16 de agosto de 2020: revisão e seleção de propostas Analisarei a documentação do ESLint e desenvolverei as habilidades necessárias para concluir o projeto, como escrita em Markdown e colaboração no GitHub. Também vou contribuir com a documentação pelo GitHub e interagir com outras pessoas para entender melhor a documentação.

De 17 de agosto de 2020 a 13 de setembro de 2020: interação com a comunidade Durante o período de engajamento, vou refinar minha proposta de acordo com as discussões com mentores e equipes interessadas. Também vou editar os objetivos e marcos, se necessário. Além disso, selecionarei as ferramentas que serão usadas para trabalhar no projeto.

14 de setembro de 2020 a 19 de setembro de 2020: auditoria de conteúdo Para começar o projeto, vou realizar uma auditoria abrangente do conteúdo da documentação de configuração. O objetivo seria destacar problemas com o conteúdo e a apresentação.

20 de setembro de 2020 a 25 de setembro de 2020: arquitetura da informação (AI) Após a auditoria de conteúdo, criarei a AI da documentação de configuração. Vou me concentrar em apresentar a rede de conhecimento de uma forma compreensível. Isso ajudará a melhorar o fluxo de informações.

26 de setembro de 2020 a 30 de setembro de 2020: links e referência Analisarei a AI durante essa fase para mapear links e referências entre várias seções da documentação. Também vou criar uma hierarquia de todas as seções, melhorando a AI no processo.

De 1o a 3 de outubro de 2020: o mapa final Com a ajuda dos insights obtidos com a auditoria de conteúdo e a AI, criarei um mapa final para ser implementado na documentação de configuração reorganizada. Esse mapa abrangente conterá um índice, uma hierarquia de tópicos e uma lista de links e referências cruzadas entre seções da documentação.

De 4 a 5 de outubro de 2020: discussão Neste ponto, antes de editar a documentação, vou apresentar minhas descobertas e planejar para os mentores e as equipes envolvidas. Seu feedback ajudará a refinar o plano e fazer alterações quando necessário.

De 6 a 20 de outubro de 2020: reescrita e edição Neste período, vou editar e atualizar as seções dos documentos quando necessário. Algumas seções da documentação de configuração podem ser reescritas ou algumas coisas novas podem ser adicionadas a elas. O foco desta fase será garantir que a documentação seja precisa, atualizada, flexível e reutilizável.

21 de outubro de 2020 a 25 de outubro de 2020: correções e links Nesta fase, vou revisar meu próprio trabalho para me livrar de erros gramaticais e estruturais e também verificar a precisão do meu trabalho. Também adicionarei links e referências entre as seções, de acordo com a AI, para garantir que a documentação siga o mapa de conhecimento elaborado anteriormente.

26 de outubro de 2020 a 31 de outubro de 2020: versão final para envio Vou vincular todos os arquivos do Markdown, criar um sumário e compartilhar os rascunhos com os mentores. Isso servirá como envio do primeiro rascunho, na forma de um pacote completo.

1o de novembro de 2020 a 5 de novembro de 2020: primeira revisão Durante esses cinco dias, vou discutir o primeiro rascunho com meus mentores. Vou receber o feedback deles e discutir minhas ideias com eles para criar uma lista de edições que precisam ser feitas.

6 de novembro de 2020 a 12 de novembro de 2020: primeiras edições Com a ajuda do feedback dos mentores, vou editar o primeiro rascunho da documentação. As edições reais dependem da natureza dos comentários e do feedback, mas os objetivos de reutilização, precisão e flexibilidade servirão como o centro da fase de edição.

De 13 a 15 de novembro de 2020: segunda análise Depois de concluir as edições iniciais, vou discutir o progresso mais uma vez com meus mentores e as equipes envolvidas. Essas discussões focam nas edições feitas na primeira versão e também destacam outras questões que podem ter surgido no processo de edição.

De 16 de novembro de 2020 a 19 de novembro de 2020: segundas edições Depois, dedicarei um período de quatro dias para a edição do documento. As versões produzidas serão discutidas com os mentores para que eles tenham um formato final. Ao final dessa fase, os documentos estarão na forma final, prontos para serem enviados ao site e ao repositório do GitHub.

De 20 a 23 de novembro de 2020: upload no site Depois de fazer todas as edições necessárias, o upload dos documentos será feito no site. Quaisquer problemas encontrados no processo serão tratados adequadamente, pois ainda teremos alguns dias para trabalhar na documentação.

De 24 de novembro de 2020 a 28 de novembro de 2020: relatório do projeto Um relatório detalhado do projeto será criado nesse período de cinco dias. Os objetivos, dificuldades, problemas e as soluções apresentadas farão parte do relatório do projeto. O relatório será compartilhado com os mentores para receber feedback.

De 29 de novembro de 2020 a 30 de novembro de 2020: envio final O projeto, os arquivos e o relatório dele serão enviados aos mentores. Uma revisão de todo o projeto será realizada em uma reunião/discussão com os mentores e as equipes envolvidas.

Ao longo do projeto, continuarei consultando os mentores para receber feedbacks valiosos. Todos esses marcos podem ser alterados com base nas discussões com os mentores nos períodos de vínculo da comunidade e de revisão da proposta.

Sobre mim Tenho graduação em Engenharia Elétrica e graduação em Comunicação Técnica e Profissional pela Universidade Estadual da Carolina do Norte. Tenho experiência nas áreas de redação e edição técnica e profissional, comunicação e gerenciamento de conteúdo, estudos de usabilidade na Web e em dispositivos móveis e design de instruções. Trabalhei como subeditor de uma publicação on-line (Global Village Space) e como estagiária de comunicações do Duke Forge na Duke University. Além disso, também tenho interesse em escrita criativa.