Projet ESLint

Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.

Résumé du projet

Organisation Open Source:

ESLint

Rédacteur technique:

Khawar

Nom du projet:

Réorganiser/Réécrire la documentation sur la configuration

Durée du projet:

Durée standard (3 mois)

Project description

Abstraite

L'objectif de ce projet est de restructurer la documentation de configuration d'ESLint et de créer une architecture de l'information efficace. Cela facilitera la navigation et améliorera également la convivialité et l'utilité de la documentation.

Résumé du projet La documentation de configuration d'ESLint (https://eslint.org/docs/user-guide/Configure) dans son état actuel fournit de nombreuses informations sur une seule page. Malgré la présence de titres, de sous-titres et de paragraphes appropriés sur la page, la documentation peut devenir accablante. Il n'existe aucun moyen d'accéder à une section particulière de la page, ce qui peut être frustrant pour les internautes intéressés par cette section. Les informations, en raison de ce manque d'organisation, peuvent également se perdre, ne pas atteindre leur objectif et demander aux utilisateurs de fournir des efforts supplémentaires.

Toutefois, ces problèmes peuvent être résolus à l'aide d'une série d'étapes minutieuses. Je propose un audit de contenu comme première étape de cette réorganisation. Un audit de contenu permettra non seulement d'identifier les problèmes dans la présentation des informations, mais aussi de mettre en évidence les lacunes du contenu lui-même (par exemple, des informations obsolètes ou incomplètes). Je prévois ensuite de créer l'architecture des informations (AI) afin de révéler le réseau de connaissances. Cela nous permettra de regrouper les informations selon différents sujets et d'établir des liens entre divers sujets étroitement liés. Les connaissances acquises grâce à ces deux pratiques seront ensuite utilisées pour diviser la documentation d'une seule page en plusieurs pages. L'ensemble du package peut ensuite être lié et recoupé dans Markdown. Vous disposerez ainsi d'une version mieux organisée de la documentation sur la configuration, plus facile à parcourir et à comprendre.

Motivation Bien que j'utilise des logiciels Open Source depuis un certain temps, je connais ce terme plutôt que les logiciels Linting. Lorsque j'ai commencé à apprendre Python (via edX), je me suis demandé comment des erreurs minuscules pouvaient gâcher l'ensemble du code. J'ai pensé qu'il serait intéressant que vos codes soient testés, d'une manière ou d'une autre, et que vos erreurs soient identifiées, puis j'ai découvert le terme "linting". Je n'ai pas encore utilisé de logiciel d'analyse lint, mais je suis sûr que cela va me faciliter la vie dans les jours à venir.

Grâce à mon expérience en génie électrique et à une certaine expérience en programmation, je comprends mieux les problèmes liés au codage et les exigences des programmeurs. De plus, mon diplôme d'études supérieures en communication technique et professionnelle me permet de défendre les utilisateurs et de leur faciliter la vie. Mes compétences et mon expertise constitueront une bonne combinaison pour ce projet et ajouteront de la valeur à la documentation d'ESLint.

Objectifs L'objectif principal de ce projet est de s'assurer que la documentation disponible sur la page de configuration d'ESLint est facile à comprendre et ne submerge pas les utilisateurs. Il est important pour la réussite du projet que la navigation dans le contenu soit facile et exempte de toute complication. Les objectifs importants du projet sont les suivants. - Réaliser un audit de contenu complet - Créer une architecture de l'information pour comprendre le flux d'informations - Améliorer l'architecture de l'information pour réorganiser la documentation - Identifier les liens et les références entre les différentes sections de contenu - Réécrire/modifier certaines parties de la documentation, si nécessaire, pour répondre aux exigences de reconfiguration

- S'assurer que le contenu est flexible et réutilisable

Description du projet La configuration d'ESLint est une fonctionnalité importante qui permet de personnaliser ESLint. Les utilisateurs intéressés par la configuration seront très certainement intéressés par un ou deux aspects à un moment donné. Il est donc important qu'un utilisateur soit guidé vers le sujet qui l'intéresse, lui fournissant ainsi la solution efficacement. La documentation actuelle sur la configuration d'ESLint contient de nombreuses informations utiles, mais celles-ci sont organisées de telle sorte que les utilisateurs se sentent dépassés, frustrés et perdus. Par exemple, si une personne souhaite en savoir plus sur l'utilisation de plug-ins tiers dans ESLint, elle devra faire défiler vers le bas la discussion sur la spécification de l'analyseur, des environnements et des éléments généraux. L’ensemble de la pratique est fatigant pour les utilisateurs et peut les conduire à quitter le site Web. De même, si un utilisateur se trouve quelque part au milieu de la page et veut accéder à une section particulière ou simplement examiner des sujets similaires, cela ne sera pas une tâche facile pour lui, car aucune aide de ce type n'est fournie aux utilisateurs. Ces questions requièrent une attention immédiate, car la qualité de toute documentation, quelle que soit sa rédaction, dépend de son utilité. Je propose des solutions à ces problèmes et à d'autres problèmes connexes dans la discussion qui suit.

Audit de contenu La première étape du processus de réorganisation de la documentation de configuration consiste à réaliser un audit de contenu complet. L'audit vise à identifier certains problèmes clés tels que le contenu obsolète, la duplication, le contenu manquant, etc. Une feuille de calcul d'audit de contenu créée en conséquence sera partagée avec les équipes de gestion et de documentation pour obtenir leurs commentaires. Cela vous aidera à élaborer une nouvelle stratégie pour structurer et présenter la documentation.

Création d'une architecture des informations Pour comprendre le réseau de connaissances ou le flux d'informations dans la documentation de configuration, la création d'une architecture des informations (AI) peut s'avérer utile. Les résultats de l'audit de contenu serviront de base pour comprendre et développer le flux d'informations. Une version améliorée de l'AI sera alors créée pour organiser et présenter la documentation d'une meilleure façon. Cette meilleure AI permettra non seulement de restructurer le contenu actuel, mais aussi d'identifier les liens et les bifurcations entre les différentes sections de la documentation, créant ainsi un réseau efficace. Par exemple, le contenu de la section "Configurer des règles" peut être suivi d'un lien menant à la section "Règles de désactivation avec des commentaires intégrés". D'autres liens de ce type peuvent également être identifiés, créant ainsi des relations entre les différentes sections de la documentation.

Un audit de la table des matières et l'AI fourniront les informations adéquates pour créer une table des matières détaillée avec des liens menant à des sections et sous-sections spécifiques de la documentation. Le fait de créer des fichiers distincts pour chaque section et d'ajouter les références appropriées aux autres sections peut ajouter de la valeur à l'ensemble des documents. Vous pouvez créer une table des matières pour les utilisateurs qui accèdent à la documentation de configuration afin de faciliter leur parcours sur le site Web. La table des matières peut inclure tous les titres des premier et deuxième niveaux afin qu'elle soit brève mais complète. Une de ces pratiques, par exemple, est celle utilisée par Prettier (https://prettier.io/docs/en/index.html) pour organiser la documentation.

Toute la documentation sera créée à l'aide de Markdown pour que les choses restent simples et bien organisées. Nous veillons tout particulièrement à ce que la documentation soit réutilisable, car elle pourrait évoluer et s'adapter par la suite.

Outils à utiliser Quelques outils importants qui peuvent être utiles lorsque vous travaillez sur un projet sont - Draw.io pour créer des illustrations pour AI si nécessaire - Atom (ou un éditeur similaire) pour écrire et modifier des documents en Markdown

- GitHub pour assurer le contrôle des versions de la documentation

Jalons De la soumission de la proposition à la réalisation du projet, les jalons provisoires suivants garantiront que le projet est terminé à temps, en maintenant le bon flux dans le processus.

Du 10 juillet 2020 au 16 août 2020: examen et sélection des propositions Je vais parcourir la documentation d'ESLint et développer les compétences nécessaires pour mener à bien le projet (comme l'écriture Markdown, la collaboration sur GitHub). Je contribuerai également à la documentation via GitHub et je travaillerai avec d'autres personnes pour mieux comprendre la documentation.

17 août 2020 – 13 septembre 2020: association avec la communauté Pendant la période d'association avec la communauté, j'affinerai ma proposition en fonction des discussions avec les mentors et les équipes concernées. Je modifierai également les objectifs et les jalons si nécessaire. En outre, je veillerai à sélectionner les outils qui seront ensuite utilisés pour travailler sur le projet.

Du 14 septembre 2020 au 19 septembre 2020: audit de contenu Pour commencer le projet, je vais effectuer un audit complet du contenu de la documentation de configuration. L'objectif est de mettre en évidence les problèmes liés au contenu et à sa présentation.

Du 20 septembre 2020 au 25 septembre 2020: Architecture des informations (AI) Après l'audit de contenu, je créerai l'AI de la documentation de configuration. Je vais me concentrer sur la présentation du réseau de connaissances de façon compréhensible. Cela permettra ensuite d'améliorer le flux d'informations.

26 septembre 2020 – 30 septembre 2020: liens et références J'analyserai l'AI au cours de cette phase pour identifier les liens et les références entre les différentes sections de la documentation. Je vais également créer une hiérarchie de toutes les sections, ce qui améliorera l'AI dans le processus.

Du 1er octobre 2020 au 3 octobre 2020: la carte finale En m'appuyant sur les informations recueillies grâce à l'audit de contenu et à l'AI, je vais créer une carte finale à implémenter dans la documentation de configuration réorganisée. Cette carte complète contiendra une table des matières, une hiérarchie des sujets, ainsi qu'une liste de liens et de références croisées entre les différentes sections de la documentation.

Du 4 octobre 2020 au 5 octobre 2020: discussion À ce stade, c'est-à-dire avant de modifier la documentation, je vais présenter mes conclusions et mon plan aux mentors et aux équipes concernées. Leurs commentaires aideront à affiner le plan et à apporter des modifications si nécessaire.

Du 6 octobre 2020 au 20 octobre 2020: réécriture et modification Au cours de cette période, je vais modifier et mettre à jour les sections des documents qui doivent être retravaillées. Certaines sections de la documentation de configuration peuvent être réécrites ou des éléments peuvent y être ajoutés. L'objectif de cette phase sera de s'assurer que la documentation est exacte, mise à jour, flexible et réutilisable.

Du 21 octobre 2020 au 25 octobre 2020: corrections et liens Au cours de cette phase, je vais examiner mon propre travail afin de me débarrasser des erreurs grammaticales et structurelles, mais aussi de vérifier l'exactitude de mon travail. J'ajouterai également des liens et des références entre les sections, conformément à l'AI, pour m'assurer que la documentation suit la carte de connaissances conçue précédemment.

Du 26 octobre 2020 au 31 octobre 2020: version finale à l’envoi Je vais lier tous les fichiers Markdown, créer une table des matières et partager les brouillons avec les mentors. Elle servira à envoyer la première ébauche, sous la forme d'un dossier complet.

Du 1er novembre 2020 au 5 novembre 2020: première révision Au cours de ces cinq jours, je discuterai de la première ébauche avec mes mentors. Je recueillerai leurs commentaires et j'échangerai avec eux sur mes idées afin de dresser une liste des modifications à apporter.

6 novembre 2020 – 12 novembre 2020: premières modifications En m'appuyant sur les commentaires des mentors, je vais modifier la première version de la documentation. Les modifications à proprement parler dépendent de la nature des commentaires, mais des objectifs de réutilisation, de précision et de flexibilité sont au cœur de la phase d'édition.

Du 13 novembre 2020 au 15 novembre 2020: deuxième examen Une fois les modifications initiales terminées, je pourrai discuter de nouveau des progrès avec mes mentors et les équipes concernées. Ces discussions porteront principalement sur les modifications apportées à la première version et sur les autres problèmes survenus au cours du processus d'édition.

Du 16 novembre 2020 au 19 novembre 2020: Deuxièmes modifications Je consacrerai ensuite un délai de quatre jours à la modification du document. Les versions produites en conséquence seront discutées avec les mentors pour leur donner une forme finale. À l'issue de cette phase, les documents sont au format final et prêts à être importés sur le site Web et dans le dépôt GitHub.

Du 20 au 23 novembre 2020: importation sur le site Web Une fois toutes les modifications nécessaires effectuées, les documents seront importés sur le site Web. Étant donné que nous aurons encore quelques jours pour travailler sur la documentation, tous les problèmes rencontrés pendant la procédure seront traités en conséquence.

Du 24 novembre 2020 au 28 novembre 2020: rapport sur le projet Un rapport détaillé sur le projet sera créé pendant cette période de cinq jours. Les objectifs, les difficultés, les problèmes et les solutions présentées feront partie du rapport du projet. Le rapport sera partagé avec les mentors pour recueillir leurs commentaires.

Du 29 novembre 2020 au 30 novembre 2020: envoi final Le projet, tous les fichiers et le rapport du projet seront envoyés aux mentors. Un examen de l'ensemble du projet sera réalisé au cours d'une réunion ou d'une discussion avec les mentors et les équipes concernées.

Tout au long du projet, je continuerai à consulter les mentors pour obtenir leurs précieux commentaires. Tous ces jalons peuvent être modifiés en fonction des discussions avec les mentors lors des périodes d'association avec la communauté et d'examen des propositions.

À propos de moi J'ai un diplôme de premier cycle en génie électrique et un diplôme d'études supérieures en communication technique et professionnelle de l'Université d'État de Caroline du Nord. J'ai de l'expérience dans les domaines de la rédaction et de l'édition techniques et professionnelles, de la communication et de la gestion de contenu, des études d'utilisabilité Web et mobile, et de la conception d'instructions. J'ai travaillé en tant que sous-rédacteur en chef d'une publication en ligne (Global Village Space) et en tant que stagiaire en communication pour Duke Forge à l'université de Duke. Je m'intéresse également à l'écriture créative.