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:

Documentation sur la réorganisation/réécriture de 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 pour ESLint et de créer une architecture des informations 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/Configuring) 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 envahissante. Il n'existe aucun moyen d'accéder à une section particulière de la page, ce qui est frustrant pour un utilisateur intéressé par cette section. Les informations, en raison de ce manque d'organisation, peuvent également être perdues, ne pas servir leur objectif et demander aux utilisateurs de fournir des efforts supplémentaires.

Cependant, ces problèmes peuvent être résolus en suivant 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) pour révéler le réseau de connaissances. Cela nous permettra de regrouper les informations en fonction de différents sujets et de trouver des liens entre divers sujets étroitement liés. Les informations obtenues 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 croisé dans Markdown. Vous bénéficierez donc 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 depuis un certain temps, tout comme je connais les logiciels lint. Quand j'ai commencé à apprendre Python (via edX), je me suis demandé comment de petites erreurs pouvaient gâcher tout le code. J'ai pensé qu'il serait utile de tester vos codes et d'identifier vos erreurs, 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 à mes connaissances en génie électrique et à la programmation, je peux mieux comprendre les problèmes de 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 apporteront une valeur ajoutée à 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. Pour la réussite du projet, il est important que la navigation dans le contenu soit facile et exempte de toutes les complications. Les objectifs importants du projet sont les suivants. - Réaliser un audit complet du contenu - Créer une architecture des informations pour comprendre le flux d'informations - Améliorer l'architecture des informations pour réorganiser la documentation - Identifier les liens et les références entre les différentes sections du contenu - Réécrire ou modifier des 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 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, ce qui lui permet de trouver efficacement la solution. La documentation sur l'état actuel de la configuration pour ESLint contient de nombreuses informations utiles, mais elle est organisée de telle sorte que les utilisateurs se sentent dépassés, frustrés ou 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. Cette pratique est fatigante 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, ce ne sera pas une tâche facile pour lui, car aucune aide de ce type n'est fournie aux utilisateurs. Ces problèmes nécessitent 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 les contenus obsolètes, les doublons, le contenu manquant, etc. Une feuille de calcul d'audit de contenu créée à la suite sera partagée avec les équipes de gestion et de documentation pour recueillir 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 être 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 ensuite créée pour organiser et présenter la documentation d'une meilleure manière. Cette amélioration de l'AI restructurera non seulement le contenu actuel, mais identifiera également les liens et bifurcations entre les différentes sections de la documentation, créant ainsi un réseau efficace. Par exemple, le contenu de la section "Configuration des règles" peut être suivi d'un lien menant à "Désactiver des règles avec des commentaires intégrés". D'autres liens de ce type peuvent également être identifiés, créant ainsi des relations entre différentes sections de la documentation.

Un audit de la table des matières et une AI fourniront des 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. La création de fichiers distincts pour chaque section et l'ajout de références appropriées aux autres sections peuvent apporter une valeur ajoutée à l'ensemble des documents. Vous pouvez créer une table des matières pour les utilisateurs qui accèdent à la documentation de configuration, ce qui facilite leur parcours sur le site Web. La table des matières peut inclure tous les en-têtes de premier et deuxième niveau afin qu'elle reste brève mais complète. L'une de ces pratiques, par exemple, est celle utilisée par Prettier (https://prettier.io/docs/fr/index.html) pour organiser la documentation.

Toute la documentation sera créée à l'aide de Markdown pour que tout soit simple et bien organisé. Une attention particulière sera mise en place pour s'assurer que la documentation est réutilisable, car elle pourrait croître et évoluer à l'avenir.

Outils à utiliser Certains outils importants qui peuvent s'avérer utiles lorsque vous travaillez sur un projet sont les suivants : - Draw.io, pour créer des illustrations pour AI, selon les besoins - Atom (ou un éditeur similaire) pour écrire et modifier des documents en Markdown

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

Étapes importantes De la soumission de la proposition à la réalisation du projet, les étapes provisoires suivantes garantissent que le projet est terminé à temps, tout 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 au format Markdown et la collaboration sur GitHub). Je contribuerai également à la documentation via GitHub et je dialoguerai avec d'autres personnes pour mieux comprendre la documentation.

17 août 2020 – 13 septembre 2020: cohésion de la communauté Pendant la période de cohésion de 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. De plus, 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, j'effectuerai 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 Je vais analyser 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: carte finale Grâce aux insights obtenus grâce à l'audit de contenu et à l'AI, je vais créer une carte finale qui sera implémentée dans la documentation de configuration réorganisée. Cette carte complète contient 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.

4 octobre 2020 – 5 octobre 2020: discussion À ce stade, c'est-à-dire avant de modifier la documentation, je présenterai 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 Pendant cette période, je vais modifier et mettre à jour les sections des documents qui nécessitent du travail. 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 passer en revue 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 s'assurer que la documentation suit la carte de connaissances conçue précédemment.

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

Du 1er novembre 2020 au 5 novembre 2020: premier examen Au cours de ces cinq jours, je discuterai de la première ébauche avec mes mentors. Je vais recueillir leurs commentaires et discuter de mes idées avec eux afin de dresser une liste des modifications à apporter.

6 novembre 2020 – 12 novembre 2020: premières modifications Sur la base des commentaires des mentors, je modifierai la première version de la documentation. Les modifications effectuées dépendront de la nature des commentaires et des réactions, mais les objectifs de réutilisation, de précision et de flexibilité serviront de point de départ pour la phase de montage.

13 novembre 2020 – 15 novembre 2020: deuxième examen Une fois les modifications initiales effectuées, je discuterai encore une fois 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 lors du processus de modification.

16 novembre 2020 – 19 novembre 2020: deuxièmes modifications Je vais ensuite consacrer une période 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 novembre 2020 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. Tout problème rencontré au cours de la procédure sera traité en conséquence, car nous aurons encore quelques jours pour travailler sur la documentation.

Du 24 novembre 2020 au 28 novembre 2020: rapport du projet Un rapport détaillé du projet sera créé dans 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 leur avis.

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

Tout au long du projet, je continuerai à consulter les mentors afin d’obtenir leurs précieux commentaires. Tous ces jalons peuvent être modifiés en fonction des discussions avec les mentors au cours des périodes de collaboration 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 pour une publication en ligne (Global Village Space) et en tant que stagiaire en communication pour Duke Forge à l'université Duke. Je m'intéresse également à l'écriture créative.