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 Google Season of Docs.

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 (três meses)

Project description

Resumo

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/configuring), 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 se tornar opressiva. 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 o propósito e exigindo mais esforço dos usuários.

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 apenas ajudará a identificar os problemas na apresentação das informações, mas também destacará as falhas do próprio conteúdo (por exemplo, informações desatualizadas ou incompletas). Em seguida, pretendo criar a arquitetura da informação (AI) para revelar a rede de conhecimento. Isso nos permitirá agrupar as informações de acordo com vários tópicos e encontrar links entre vários tópicos estreitamente relacionados. Os insights obtidos com essas duas práticas serão usados para dividir a documentação de uma página em várias páginas. O pacote inteiro pode ser vinculado e referenciado em Markdown. Como resultado, haverá uma versão melhor organizada da documentação de configuração, que será mais fácil de navegar e entender.

Motivação Apesar de eu usar softwares de código aberto há algum tempo, minha familiaridade com o termo é bastante recente, assim como meu conhecimento sobre softwares de linting. Quando comecei a aprender Python (pelo edX), me perguntei como erros pequenos podem bagunçar todo o código. Achei que seria bom testar seus códigos de alguma forma e identificar os erros. Então, descobri o termo "linting". Ainda não usei o linting, mas tenho certeza de que isso vai 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 melhor os problemas da programação e os requisitos dos programadores. Além disso, meu diploma de graduação em Comunicação Técnica e Profissional me torna um defensor dos usuários, tentando facilitar a vida deles. Minhas habilidades e experiência serão 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. Para o sucesso do projeto, é importante 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 da informação 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

- O conteúdo é 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 em configuração provavelmente vão se interessar por um ou dois aspectos em um determinado momento. Portanto, é importante que o usuário seja orientado a um tópico de interesse específico, para que possa encontrar a solução de maneira eficiente. O estado atual da documentação de configuração do ESLint contém muitas informações úteis, mas está organizado de uma forma que pode deixar os usuários sobrecarregados, frustrados e perdidos. Por exemplo, se alguém tiver interesse em saber mais sobre o uso de plug-ins de terceiros no ESLint, ele terá que rolar para baixo, passando pela discussão sobre como especificar parsers, ambientes e variáveis globais. O processo todo é cansativo para os usuários e pode afastá-los do site. Da mesma forma, se um usuário estiver no meio da página e quiser acessar uma seção específica ou apenas conferir tópicos semelhantes, não será uma tarefa fácil para ele, já que não há ajuda desse tipo. Esses problemas precisam de atenção imediata, pois a qualidade de qualquer documentação, por mais que seja bem elaborada, depende da utilidade dela. Proponho soluções para esses e outros problemas relacionados na discussão a seguir.

Auditoria de conteúdo A primeira etapa do processo de reorganização da documentação de configuração é realizar uma auditoria abrangente do conteúdo. A auditoria terá como objetivo identificar alguns problemas importantes, como conteúdo desatualizado, duplicação, conteúdo ausente etc. Uma planilha de auditoria de conteúdo criada como resultado será compartilhada com as equipes de gerenciamento e documentação para receber feedback. Isso vai ajudar a criar uma nova estratégia para estruturar e apresentar a documentação.

Criação de 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 uma arquitetura da informação (AI) pode ser útil. As descobertas da auditoria de conteúdo vão servir como uma boa base para entender e desenvolver o fluxo de informações. Uma versão melhorada da IA será 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á vínculos e bifurcações entre várias seções da documentação, criando assim uma rede eficiente. Por exemplo, o conteúdo em "Configurar regras" pode ser seguido por um link que leva a "Desativar regras com comentários inline". Outros links semelhantes também podem ser identificados, criando relações entre diferentes seções da documentação.

Uma tabela de conteúdo A auditoria de conteúdo e a IA vão fornecer informações adequadas para criar uma tabela de conteúdo detalhada com links para seções e subseções específicas da documentação. Criar arquivos separados para cada seção e adicionar referências adequadas 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 deles no site. O sumário pode incluir todos os cabeçalhos de primeiro e segundo nível para que seja breve, mas 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 especial para garantir que a documentação seja reutilizável, já que ela pode crescer e mudar no futuro.

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

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

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

10 de julho de 2020 a 16 de agosto de 2020: análise e seleção de propostas Vou analisar a documentação do ESLint e desenvolver as habilidades necessárias para concluir o projeto (como escrever em Markdown e colaborar no GitHub). Também vou contribuir com a documentação no GitHub e interagir com outras pessoas para entender melhor a documentação.

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

14 a 19 de setembro de 2020: auditoria de conteúdo Para começar o projeto, vou realizar uma auditoria de conteúdo abrangente da documentação de configuração. O objetivo é destacar os 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) Depois da 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 maneira compreensível. Isso ajudará a melhorar o fluxo de informações.

26 a 30 de setembro de 2020: links e referências Vou analisar a IA 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 IA no processo.

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

4 a 5 de outubro de 2020: discussão Neste ponto, antes de editar a documentação, vou apresentar minhas descobertas e meu plano aos mentores e às equipes envolvidas. O feedback deles vai ajudar a refinar o plano e fazer alterações quando necessário.

6 a 20 de outubro de 2020: reescrita e edição Nesse período, vou editar e atualizar as seções dos documentos em que é necessário trabalhar. Algumas seções da documentação de configuração podem ser reescritas ou novas informações podem ser adicionadas a ela. O foco nesta 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 para verificar se está correto. Também vou adicionar links e referências entre as seções, de acordo com a IA, 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 Markdown, criar uma tabela de conteúdo e compartilhar os rascunhos com os mentores. Isso servirá como o envio do primeiro rascunho, na forma de um pacote completo.

1º a 5 de novembro de 2020: primeira revisão Durante esses cinco dias, vou discutir o primeiro rascunho com meus mentores. Vou receber feedback 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 servem como local da fase de edição.

13 a 15 de novembro de 2020: segunda revisão Depois de concluir as edições iniciais, vou discutir o progresso com meus mentores e as equipes envolvidas mais uma vez. Essas discussões vão se concentrar nas edições feitas na primeira versão e também destacar outros problemas que possam ter surgido no processo de edição.

De 16 de novembro de 2020 a 19 de novembro de 2020: segunda edição Dedicarei um período de quatro dias para editar o documento. As versões produzidas como resultado serão discutidas com os mentores para dar a eles uma forma final. Ao final desta fase, os documentos estarão na forma final, prontos para serem enviados ao site e ao repositório do GitHub.

20 a 23 de novembro de 2020: upload no site Depois de fazer todas as edições necessárias, os documentos serão enviados para o site. Qualquer problema encontrado no processo será resolvido de acordo, já que ainda temos alguns dias para trabalhar na documentação.

24 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 soluções apresentadas farão parte do relatório do projeto. O relatório será compartilhado com os mentores para receber feedback.

29 a 30 de novembro de 2020: envio final O projeto, todos os arquivos e o relatório do projeto serão enviados aos mentores. A revisão de todo o projeto será realizada por meio de uma reunião/discussão com os mentores e as equipes em questão.

Ao longo do projeto, vou continuar consultando os mentores para receber feedback valioso. Todos esses marcos podem ser alterados com base nas discussões com os mentores nos períodos de vinculação à comunidade e de análise da proposta.

Sobre mim Sou formada em Engenharia Elétrica e pós-graduada 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ário de comunicação da Duke Forge na Universidade Duke. Além disso, também tenho interesse em escrita criativa.