Cette page a été traduite par l'API Cloud Translation.

Projet ESLint

Cette page contient les détails d'un projet de rédaction technique accepté pour la 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 (trois mois)

Project description

Extrait

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 l'usabilité 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 être difficile à suivre. Il n'est pas possible d'accéder à une section spécifique de la page, ce qui est frustrant pour un utilisateur intéressé par une section spécifique. En raison de ce manque d'organisation, les informations peuvent également se perdre, 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 de mesures minutieuses. Je propose un audit de contenu comme première étape de cette réorganisation. Un audit de contenu permet non seulement d'identifier les problèmes de 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 de l'information (AI) pour dévoiler le réseau de connaissances. Cela nous permettra de regrouper les informations selon différents thèmes et de trouver des liens entre différents sujets étroitement liés. Les insights obtenus grâce à ces deux pratiques seront ensuite utilisés pour diviser la documentation en une seule page en plusieurs pages. L'ensemble du package peut ensuite être lié et croisé dans Markdown. Vous obtiendrez ainsi une version de la documentation de configuration mieux organisée, plus facile à parcourir et à comprendre.

Motivation Bien que j'utilise des logiciels Open Source depuis un certain temps, je ne suis que récemment devenu familier avec ce terme, tout comme avec les logiciels de linting. Lorsque j'ai commencé à apprendre Python (via edX), je me suis demandé comment de minuscules erreurs pouvaient gâcher l'ensemble du code. J'ai pensé qu'il serait bien de faire tester vos codes d'une manière ou d'une autre et d'identifier vos erreurs. J'ai alors découvert le terme "linting". Je n'ai pas encore utilisé de logiciel de linting, mais je suis sûr que cela me facilitera la vie dans les jours à venir.

Grâce à mon expérience 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 de master en communication technique et professionnelle me permet de défendre les utilisateurs et de leur simplifier la vie. Mes compétences et mon expertise seront un bon mélange pour ce projet, et apporteront de la valeur à la documentation d'ESLint.

Objectifs L'objectif global de ce projet est de s'assurer que la documentation de 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 simple et sans complications. Les principaux objectifs 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 afin de réorganiser la documentation - Identifier les liens et les références entre différentes sections du contenu - Réécrire/Modifier les parties de la documentation, si nécessaire pour répondre aux exigences de reconfiguration

- Veiller à ce que le contenu soit flexible et réutilisable

Description du projetLa configuration d'ESLint est une fonctionnalité importante qui permet de le personnaliser. Les utilisateurs intéressés par la configuration seront très certainement intéressés par un ou deux aspects à la fois. Il est donc important que l'utilisateur soit guidé vers le sujet qui l'intéresse, ce qui lui permet de trouver la solution le plus efficacement possible. La documentation de configuration actuelle d'ESLint contient de nombreuses informations utiles, mais elle est organisée de manière à pouvoir submerger, frustrer et désorienter les utilisateurs. Par exemple, si quelqu'un souhaite en savoir plus sur l'utilisation de plug-ins tiers dans ESLint, il 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 éloigner du site Web. De même, si un utilisateur se trouve au milieu de la page et souhaite accéder à une section spécifique ou simplement consulter des sujets similaires, il ne sera pas facile pour lui de le faire, car aucune aide de ce type n'est fournie. Ces problèmes doivent être traités immédiatement, car la qualité de toute documentation, même si elle est bien rédigée, dépend de son utilité. Je propose des solutions à ces problèmes et à d'autres problèmes connexes dans la discussion qui suit.

Audit du contenu La première étape du processus de réorganisation de la documentation de configuration consiste à réaliser un audit complet du contenu. L'audit vise à identifier certains problèmes clés tels que le contenu obsolète, les doublons, le contenu manquant, etc. La feuille de calcul d'audit de contenu créée sera partagée avec les équipes de gestion et de documentation pour obtenir leurs commentaires. Cela vous aidera à élaborer une nouvelle stratégie de structuration et de présentation de 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 façon. Cette IA améliorée ne restructurera pas seulement le contenu actuel, mais identifiera également les liens et les embranchements 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 à "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.

Une table des matières L'audit du contenu et l'IA fourniront des informations adéquates pour créer une table des matières détaillée avec des liens vers des sections et des sous-sections spécifiques de la documentation. Créer des fichiers distincts pour chaque section et ajouter des références appropriées aux autres sections peut ajouter de la valeur à l'ensemble des documents. Une table des matières peut être créée pour les utilisateurs qui accèdent à la documentation de configuration, afin de faciliter leur parcours sur le site Web. Le sommaire peut inclure tous les titres de premier et de deuxième niveau pour être bref, mais complet. Prettier (https://prettier.io/docs/en/index.html), par exemple, utilise une telle pratique 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 veillerons à ce que la documentation soit réutilisable, car elle pourra évoluer et s'étendre à l'avenir.

Outils à utiliserVoici quelques outils importants qui peuvent vous être utiles lorsque vous travaillez sur le projet : - Draw.io pour créer des illustrations pour l'IA si nécessaire - Atom (ou un éditeur similaire) pour écrire et modifier des documents en Markdown

- GitHub pour assurer le contrôle de version de la documentation

Jalons Du dépôt de la proposition à la finalisation du projet, les jalons provisoires suivants vous permettront de vous assurer que le projet est terminé à temps, tout en maintenant le bon flux dans le processus.

10 juillet 2020 - 16 août 2020: examen et sélection des propositionsJ'examinerai la documentation d'ESLint et développerai les compétences nécessaires pour mener à bien le projet (comme l'écriture en Markdown et la collaboration sur GitHub). Je contribuerai également à la documentation via GitHub et échangerai avec d'autres personnes pour mieux la comprendre.

17 août 2020 – 13 septembre 2020: renforcement des liens au sein de la communautéPendant cette période, je vais affiner 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 m'assurerai de dresser une liste restreinte des outils qui seront utilisés pour travailler sur le projet.

14 septembre 2020 à 19 septembre 2020: audit du 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.

20 septembre 2020 - 25 septembre 2020: architecture de l'information (AI) Après l'audit du contenu, je vais créer l'AI de la documentation de configuration. Je vais me concentrer sur la présentation du réseau de connaissances de manière claire. Cela vous aidera à améliorer le flux d'informations.

Du 26 septembre 2020 au 30 septembre 2020: liens et références J'analyserai l'AI au cours de cette phase afin d'établir 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'IA.

Du 1er octobre 2020 au 3 octobre 2020: carte finale À l'aide des insights obtenus via l'audit de contenu et l'AI, je créerai ensuite une carte finale à implémenter dans la documentation de configuration réorganisée. Ce plan complet contient une table des matières, une hiérarchie des sujets, ainsi qu'une liste de liens et de renvois entre les 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 vous aideront à affiner le plan et à apporter les modifications nécessaires.

6 octobre 2020 à 20 octobre 2020: réécriture et révisionPendant cette période, je vais modifier et mettre à jour les sections des documents qui nécessitent un travail. Certaines sections de la documentation de configuration peuvent être réécrites ou de nouvelles sections peuvent y être ajoutées. L'objectif de cette phase est de s'assurer que la documentation est précise, à jour, flexible et réutilisable.

21 octobre 2020 – 25 octobre 2020: corrections et liens Au cours de cette phase, je vais examiner mon propre travail pour éliminer les erreurs grammaticales et structurelles, et vérifier que mon travail est précis. 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 des 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 s'agit de l'envoi de la première ébauche, sous la forme d'un package complet.

1er novembre 2020 - 5 novembre 2020: première révisionPendant ces cinq jours, je discuterai de la première ébauche avec mes mentors. Je vais recueillir ses commentaires et discuter de mes idées avec lui pour établir une liste des modifications à apporter.

6 novembre 2020 – 12 novembre 2020: premières modificationsAvec l'aide des commentaires des mentors, je vais modifier la première ébauche de la documentation. Les modifications réelles dépendent de la nature des commentaires et des commentaires, mais la phase de montage est centrée sur des objectifs de réutilisation, de précision et de flexibilité.

13 novembre 2020 – 15 novembre 2020: deuxième révisionUne fois les modifications initiales effectuées, je discuterai à nouveau de la progression avec mes mentors et les équipes concernées. Ces discussions se concentreront sur les modifications apportées à la première version et mettront en évidence les autres problèmes qui ont pu être survenus au cours du processus de modification.

16 novembre 2020 – 19 novembre 2020: deuxièmes modificationsJ'utiliserai ensuite quatre jours pour modifier le document. Les versions produites seront discutées avec les mentors pour leur donner une forme finale. Une fois cette phase terminée, les documents auront leur forme finale, 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. Tout problème rencontré au cours du processus sera traité en conséquence, car nous aurons encore quelques jours pour travailler sur la documentation.

24 novembre 2020 – 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és feront partie du rapport du projet. Le rapport sera partagé avec les mentors pour qu'ils puissent vous faire part de leurs commentaires.

29 novembre 2020 - 30 novembre 2020: Envoi finalLe projet, ainsi que tous les fichiers et le rapport de projet, seront envoyés aux mentors. Une analyse de l'ensemble du projet sera effectuée lors d'une réunion/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 pendant les périodes de renforcement des liens au sein de la communauté et d'examen des propositions.

À propos de moi Je suis titulaire d'une licence en génie électrique et d'un master 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 la révision 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é comme sous-éditeur pour une publication en ligne (Global Village Space) et comme stagiaire en communication pour Duke Forge à l'université Duke. Je m'intéresse également à l'écriture créative.