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:
- Électron
- Rédacteur technique:
- Mister Gold
- Nom du projet:
- Parcours du tutoriel Électron
- Durée du projet:
- Durée standard (trois mois)
Project description
RÉSUMÉ DU PROJET
Electron est l'un des outils les plus populaires pour créer des applications de bureau multiplates-formes avec JavaScript, HTML et CSS. Une collection d'applications créées sur Electron compte près de 900 entrées, et cette liste ne cesse de croître. Certains des outils de développement les plus populaires, comme Visual Studio Code, Atom, Postman, Slack et GitKraken, sont basés sur Electron.
La popularité d'Electron réside dans sa courbe d'apprentissage simple et son faible seuil d'entrée : tout le monde qui connaît la pile JavaScript, HTML et CSS peut créer sa propre application. Les taux de croissance globaux élevés exigent la création de tutoriels et de guides de démarrage faciles à comprendre et à utiliser.
L'objectif du projet est de donner confiance aux développeurs d'applications qui débutent avec le framework Electron et de leur offrir une expérience cohérente et simplifiée pour développer leurs propres applications Electron à partir de zéro.
Problèmes liés au projet
Vous trouverez ci-dessous la liste des problèmes les plus cruciaux liés à la documentation des tutoriels Electron : 1. Point de départ peu clair et informations d'introduction peu intuitives sur les étapes de développement d'applications. Informations éparses et redondantes sur le processus de développement d'applications. Des instructions de guide de démarrage désorganisées sans source unique
PROPOSITION DE PROJET
Selon l'objectif du projet et les problèmes décrits ci-dessus, voici une liste des améliorations proposées : 1. Mettez à jour les guides existants. Pour que les premières étapes soient fluides et cohérentes, les documents suivants doivent être mis à jour en passant progressivement du simple au plus complexe : - Environnement de développement - Écrire votre première application Electron - Ajouter des fonctionnalités à votre application (créer une page récapitulative) - Emballage et distribution d'applications 2. Restructurez le répertoire de documentation. Pour montrer aux nouveaux développeurs ce qui est essentiel pour se lancer et ce qui peut être considéré comme des étapes supplémentaires, la page de documentation doit comporter une division visuelle et contextuelle des étapes afin de rendre la première application disponible le plus rapidement possible. La restructuration comprend également des conseils sur les prochaines étapes possibles. 3. Organiser et unifier la documentation sur le développement d'applications Toutes les fonctionnalités doivent disposer d'un ensemble d'instructions unifié pour l'installation et l'activation, la prise en main rapide, l'utilisation d'une application après son premier lancement et la distribution de celle-ci. 4. Inclure le dépôt electron-api-demos dans la documentation. Le référentiel électron-api-demos contient un ensemble d'exemples qui montrent comment ajouter des fonctionnalités à votre application Electron. Ces informations doivent être incluses dans le guide "Ajouter des fonctionnalités à votre application" pour être cohérentes avec une stratégie de contenu unique et fiable. 5. Intégrer des exemples d'électron Fiddle dans la documentation. Cette étape permettra aux nouveaux développeurs de voir plus facilement comment fonctionne un code particulier sans avoir à répéter les étapes manuellement. L'intégration comprend l'écriture d'exemples de code pour les tutoriels mis à jour et l'ajout du bouton "Lancer dans Fiddle" aux blocs de code.
Temps forts
Période d'examen de la demande : familiarisez-vous avec la communauté et les personnes avec lesquelles vous allez collaborer. Découvrez les guides et les bonnes pratiques concernant les contributions à la communauté. Apportez les premières contributions. Liens communautaires : explorez la communauté. Inspectez l'état actuel de la documentation Electron. Identifiez les points faibles. Semaine 1 – Se mettre en relation avec les mentors sur les étapes importantes et les livrables du projet Semaine 2 : réviser l'environnement du développeur et rédiger les premières pages de votre application Electron Semaine 3 : réviser l'architecture de l'application, ajouter des fonctionnalités à votre application, créer le package et les pages de distribution Créez une page récapitulative avec la liste des fonctionnalités pouvant être ajoutées à l'application. Semaine 4 : Restructurez le répertoire de documentation. Semaine 5 : Préparez un modèle de l'intégration d'electron-api-demos dans la documentation principale. Semaines 6 et 7 : Migrez le dépôt electron-api-demos. Semaine 8 : Préparez un modèle de l'intégration d'Electron Fiddle dans la documentation principale. Écrivez le premier exemple. Semaines 9 à 10 : intégration de l'outil Electron Fiddle dans la documentation principale Semaine 11 : finalisation de la structure et des pages de la documentation principale après la migration du dépôt electron-api-demos et des exemples Electron Fiddle Semaine 12 : évaluation des résultats
RÉPARTITION DÉTAILLÉE DES ÉTAPES
PÉRIODE D'EXAMEN DES CANDIDATURES La première partie de cette période consiste à vérifier les canaux de la communauté et le code source, et à contacter les personnes qui se consacrent au projet.
La deuxième partie de la période sera consacrée à l'examen de la culture de contribution en général, en examinant les guides et les bonnes pratiques de contribution. Il s'agira de la première contribution pour voir comment fonctionne le flux.
SOLIDARITÉ DE LA COMMUNAUTÉ
Cette fois, nous allons examiner plus en détail le dossier de documentation et sa feuille de route. Sur la base de ces informations, vous pourrez identifier les points faibles (par exemple, des parties incomplètes ou manquantes) à améliorer. Créez des demandes d'extraction (si possible) pour combler les lacunes.
SEMAINE 1 – SEMAINE 2
La première semaine sera consacrée à la communication avec les mentors afin de s'accorder sur les jalons attendus et leur livraison dans les délais.
La deuxième semaine sera consacrée à la révision des pages "Environnement de développement" et "Écrire votre première application Electron". Pour la page "Environnement de développement", cela inclut la réécriture de la présentation générale et la relecture. Pour la page "Écrire votre première application Electron", il s'agira de la transformer en guide par étapes cohérent avec des points de départ et d'arrivée clairs, et de supprimer les informations redondantes (comme les deux blocs de code similaires dans les sections "Développement Electron en résumé" et "Essayer cet exemple").
Livrables: guides d'introduction révisés et faciles à suivre sur le démarrage rapide avec les applications Electron.
SEMAINE 3
Cette semaine, nous allons nous concentrer sur les améliorations apportées à la page "Architecture de l'application". Cela inclut : - la réécriture des informations existantes dans la section "Processus principaux et de rendu" pour les rendre plus simples et plus intuitives pour les lecteurs novices - l'ajout d'une représentation visuelle de l'architecture, de la façon dont les processus sont connectés, de la façon dont ils communiquent et de leur principale différence. Exemples de visuels: Un, Deux, Trois (de mauvaise qualité). 2. unification des informations sur toutes les fonctionnalités que vous pouvez ajouter à votre application Electron. Cela inclut la réécriture des guides afin qu'ils contiennent un ensemble unifié d'instructions sur l'installation/l'activation d'une fonctionnalité, ainsi qu'un exemple de son fonctionnement. De plus, une nouvelle page (récapitulative) listant toutes les fonctionnalités disponibles sera créée. Les instructions unifiées peuvent se présenter comme suit : - Présentation - Exemple : - Exemple de code - Exemple visuel (si possible)
- simplification de la page "Distribution des applications". Cela inclut : a. la fusion de l'empaquetage d'applications dans le guide de distribution d'applications b. la division des méthodes de distribution en automatique et manuel c. la prise d'electron-forge comme exemple de distribution automatique d. la récupération d'informations sur asar à partir de la page "Application Packaging" (Empaquetage d'applications) et la description de la copie de fichiers sources et de la création d'une archive asar comme exemples de distribution manuelle. #### SEMAINE 4 Cette semaine sera consacrée à la restructuration du répertoire de documentation. Il inclut les éléments suivants :
1 : en divisant les guides existants en au moins trois catégories : a. Démarrage rapide b. Apprendre les principes de base c. Étapes avancées
La catégorie "Démarrage rapide" contiendra les tutoriels de base (installation, configuration, distribution) afin de créer une série de guides cohérents qui permettront aux nouveaux utilisateurs de démarrer à partir de zéro. Chaque guide doit contenir des liens vers les guides précédents/suivants de la série.
La structure peut se présenter comme suit : 1. Prérequis 2. Installez Electron 3. Créer une application de base 4. Empaqueter/Distribuer l'application
Après avoir rempli la section Démarrage rapide, l'utilisateur connaîtra les bases du fonctionnement des applications Electron et disposera d'une application Electron distribuable entièrement fonctionnelle.
La catégorie "Apprendre les bases" contient les guides visant à renforcer vos connaissances sur Electron et à développer l'application créée dans les sections de démarrage rapide. Ces guides incluent : - Architecture de l'application - Ajouter des fonctionnalités à votre application - Codes récurrent et CLI
La catégorie "Étapes avancées" contient des guides plus avancés visant à configurer et à affiner votre application Electron : - Test et débogage - Accessibilité - Sécurité - Mises à jour
2 - réduire le nombre de pages de documentation. La version actuelle de la documentation contient un certain nombre de contenus qui se chevauchent et d'instructions non catégorisées. Par exemple : - Installation et installation d'Electron dans la section "Écrire votre première application" - Empaquetage d'applications et empaquetage de votre application dans un fichier dans la section "Distribution des applications" - Instructions non catégorisées dans les catégories "En détail" et "Avancé" : Suggestion: déplacez les documents suivants vers GitHub et excluez-les de la documentation principale. Ces documents sont spécifiques aux consignes de développement Electron et vous pouvez les consulter en premier lieu dans le dépôt source : - Développement d'électron - Développement Chromium - Développement V8 - Problèmes liés à Electron - Correctifs dans Electron - Requêtes d'extraction - Structure de l'annuaire du code source - Tests du style de codage
L'idée principale de cette réduction est de supprimer un nombre oppressant de guides disponibles, de rassembler les pièces du puzzle d'informations dispersées et de fournir aux nouveaux utilisateurs une version de la documentation Electron plus structurée, facile à naviguer et conviviale.
SEMAINES 5 à 7
La semaine 5 sera consacrée à la préparation d'un modèle (une méthode) d'intégration d'electron-api-demos dans la documentation principale. Ce modèle peut se présenter comme suit : 1. Dans la documentation principale, sous "Ajouter des fonctionnalités à votre application", créez les catégories représentées dans electron-api-demos 2. Passez en revue chacune des catégories, puis transférez les exemples de démonstration vers la documentation principale : - Les exemples de code peuvent être extraits du code source ou de la description de la fonctionnalité correspondante dans l'application. - Chaque exemple transféré doit être suivi de la description associée. - Chaque exemple enfant (par exemple, la boîte de dialogue d'erreur en tant qu'enfant des boîtes de dialogue système) doit être transféré sous son parent.
REMARQUE 1: Il existe des exemples dans electron-api-demos et dans la documentation principale (par exemple, les raccourcis clavier, le glisser-déposer). Dans ce cas, l'exemple de electron-api-demos doit être prioritaire et l'exemple de la documentation principale doit être ignoré.
REMARQUE 2: De nombreux exemples de l'application electron-api-demos incluent un aperçu de la fonctionnalité décrite. Cette fonctionnalité sera ignorée jusqu'à l'intégration de Electron Fiddle les semaines 9 à 10.
- Mettez à jour la page listant toutes les fonctionnalités disponibles (créée lors de la semaine 3) en respectant la nouvelle hiérarchie des exemples.
Les semaines 6 et 7 seront consacrées au transfert des exemples electron-api-demos vers la documentation principale, conformément au modèle décrit ci-dessus. La dernière étape consiste à supprimer le dépôt électron-api-demos ou à le rendre obsolète.
SEMAINES 8 – 10
La semaine 8 sera consacrée à la préparation d'un modèle (une méthode) d'intégration d'Electron Fiddle dans la documentation principale. Cette initiative a déjà été lancée (consultez les détails dans l'issue 20442) par les équipes Electron et des bénévoles de la communauté, mais elle doit être finalisée.
Pour continuer avec les exemples Fiddle, le modèle de base peut se présenter comme suit : 1. Choisissez un exemple dans la documentation principale (par exemple, le guide de démarrage rapide). À ce stade, la documentation doit également contenir des exemples de démonstrations de l'API Electron. Recréez l'exemple dans Electron Fiddle (en utilisant l'exemple de code ou le code source comme point de départ) ; 3. Enregistrez le Fiddle localement dans un dossier. 4. Déplacez l'exemple dans /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * La liste des exemples terminés est décrite dans la section "Liste des démonstrations" du problème. 5. Ajoutez le bouton "Launch in Fiddle" (Lancer dans Fiddle) comme indiqué dans le commentaire initial du problème n° 2848.
Les semaines 9 et 10 seront consacrées à l'intégration des exemples electron-api-demos (qui ont déjà été convertis en Fiddles) dans la documentation principale, conformément au modèle décrit ci-dessus.
SEMAINE 11
Cette semaine sera entièrement consacrée à la finalisation du projet d'écriture après la migration réussie du dépôt électron-api-demos et des échantillons d'Electron Fiddle. Cela inclut : - vérifier que tous les exemples de code existants comportent le bouton "Lancer dans Fiddle" - vérifier que tous les exemples de code existants fonctionnent correctement en tant que Fiddles - vérifier que la documentation principale ne fait plus référence au dépôt electron-api-demos
SEMAINE 12
Finalisation des travaux terminés Vérifications d'acceptation.