Esta página foi traduzida pela API Cloud Translation.

Projeto ESLint

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:: 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 vai facilitar a navegação e também melhorar a usabilidade e 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 de parágrafos apropriados na página, a documentação pode ficar sobrecarregada. Não é possível navegar até uma seção específica da página, o que é frustrante para um usuário interessado em uma determinada seção. Por causa dessa falta de organização, as informações também podem se perder, não cumprir a finalidade e pedir que os usuários se esforçam mais.

No entanto, esses problemas podem ser resolvidos com uma série de etapas cuidadosas. Proponho uma auditoria de conteúdo como a primeira etapa nessa reorganização. Uma auditoria de conteúdo não ajuda apenas a identificar os problemas na apresentação das informações, mas 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 comparado com o Markdown. Como resultado, vai haver uma versão mais organizada da documentação de configuraçã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 Linting. Quando comecei a aprender Python (através de edX), me perguntei como pequenos erros podem atrapalhar todo o código. Pensei que seria bom testar seus códigos de alguma forma e identificar os erros. Foi então que descobri o termo "lint". Ainda não usei um software de lint, mas tenho certeza de que isso facilitará muito minha vida nos próximos dias.

Com minha formação em engenharia elétrica e alguma experiência em programação, consigo entender os problemas de programaçã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 de conteúdo abrangente - 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;

Descrição do projeto A configuração do ESLint é um recurso importante, que torna o ESLint personalizável. Os usuários interessados na configuração certamente teriam interesse em um ou dois aspectos de uma vez. Portanto, é importante que o usuário seja direcionado para o tópico de interesse dele, oferecendo 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 quiser saber mais sobre o uso de plug-ins de terceiros no ESLint, ele precisará rolar a tela para baixo e ver a discussão sobre como especificar o analisador, os ambientes e os globais. A prática inteira é 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, já que esse tipo de auxílio não é fornecido para 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 A primeira etapa do processo de reorganização da documentação de configuração é realizar uma auditoria de conteúdo abrangente. 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 vão servir como uma boa base para entender e desenvolver o fluxo de informações. Uma versão aprimorada da AI será criada para organizar e apresentar a documentação de uma maneira melhor. Essa AI aprimorada não apenas reestrutura o conteúdo atual, mas também identifica vínculos 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 leve a "Regras de desativação com comentários inline". Outros links desse tipo também podem ser identificados, criando assim relações entre diferentes seções da documentação.

Uma auditoria de conteúdo e AI fornece informações adequadas para criar um índice 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, facilitando a jornada no site. O sumário pode incluir todos os títulos do primeiro e segundo níveis para mantê-lo breve, porém abrangente. Uma prática assim, por exemplo, é a usada pela 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 seja reutilizável, já que pode crescer e ser alterada 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 um editor semelhante) para escrever e editar documentos no Markdown

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

Marcos Desde o envio da proposta até a 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 Vou analisar a documentação do ESLint e desenvolver as habilidades necessárias para concluir o projeto (como escrita no Markdown e colaboração no GitHub). Também vou contribuir para a documentação pelo GitHub e interagir com outras pessoas para entender melhor a documentação.

17 de agosto de 2020 a 13 de setembro de 2020: vínculo com a comunidade Durante o período de conexão, vou refinar minha proposta de acordo com as discussões com mentores e equipes em questão. Também editarei os objetivos e marcos, se necessário. Além disso, vou selecionar 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 de conteúdo da documentação de configuração. O objetivo seria destacar os problemas com o conteúdo e sua 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, vou criar 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.

1o de outubro de 2020 a 3 de outubro de 2020: o mapa final Com a ajuda dos insights obtidos pela auditoria de conteúdo e pela 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 de outubro de 2020 a 5 de outubro de 2020: discussão Neste ponto, antes de editar a documentação, vou apresentar minhas descobertas e fazer um plano para os mentores e as equipes responsáveis. O feedback deles ajudará a refinar o plano e fazer alterações quando necessário.

6 de outubro de 2020 a 20 de outubro de 2020: reescrita e edição Neste período, vou editar e atualizar as seções de documentos que precisarem de trabalho. Algumas seções da documentação de configuração podem ser reescritas ou adicionadas a ela itens novos. 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 eliminar erros gramaticais e estruturais e também conferir se ele está correto. Também adicionarei links e referências entre as seções, de acordo com a AI, para garantir que a documentação esteja seguindo 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 índice e compartilhar os rascunhos com os mentores. Ele servirá como o 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 falar sobre 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 dependerão 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.

13 de novembro de 2020 a 15 de novembro de 2020: segunda revisão Após concluir as edições iniciais, vou discutir o progresso com meus mentores e com as equipes em questão mais uma vez. Essas discussões centrarão nas edições feitas na primeira versão e também destacarão quaisquer outras questões que possam ter surgido no processo de edição.

16 de novembro de 2020 a 19 de novembro de 2020: segundas edições Em seguida, 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 upload no site e no repositório do GitHub.

20 a 23 de novembro de 2020: upload no site Após fazer todas as edições necessárias, os documentos serão enviados ao site. Quaisquer problemas encontrados no processo serão tratados de acordo, já que ainda temos 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 o feedback.

29 de novembro de 2020 a 30 de novembro de 2020: envio final O projeto, os arquivos e o relatório do projeto serão enviados para os 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, vou continuar 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 criação de vínculo com a comunidade e análise das propostas.

Sobre mim Sou graduado em Engenharia Elétrica e 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, gerenciamento de comunicação e 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ário de comunicações do Duke Forge na Duke University. Além disso, também tenho interesse em escrita criativa.