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:
- Électron
- Rédacteur technique:
- Monsieur Gold
- Nom du projet:
- Procédure du tutoriel Electron
- Durée du projet:
- Durée standard (3 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 développées sur Electron compte près de 900 entrées, et cette liste ne cesse de s'allonger. Certains des outils de développement les plus populaires, tels que Visual Studio Code, Atom, Postman, Slack et GitKraken, sont basés sur Electron.
La popularité d'Electron réside dans sa simple courbe d'apprentissage et son faible seuil d'entrée. Toute personne connaissant les langages JavaScript, HTML et CSS peut créer sa propre application. Les taux de croissance globaux élevés indiquent qu'il est nécessaire de créer des tutoriels et des guides de démarrage faciles à prendre en main et à utiliser.
L'objectif de ce projet est de mettre la confiance des développeurs d'applications qui débutent avec le framework Electron et de leur fournir une expérience cohérente et simplifiée dans le développement de leurs propres applications Electron dès le départ.
Problèmes liés au projet
Voici une liste des problèmes les plus critiques liés à la documentation sur les tutoriels Electron : 1. Point de départ peu clair et informations d'introduction non intuitives sur les étapes de développement de l'application 2. Informations éparses et redondantes liées au processus de développement de l'application 3. Instructions désordonnées du guide de démarrage, sans source unique de référence
PROPOSITION DE PROJET
En fonction de l'objectif du projet et des problèmes décrits ci-dessus, voici la 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 progressivement, du plus simple au plus complexe : - Environnement du développeur - Écriture de votre première application Electron - Ajouter des fonctionnalités à votre application (créer une page de synthèse) - Mise en package et distribution d'applications 2. Restructurer le répertoire de documentation Afin de présenter aux nouveaux développeurs les éléments essentiels à la mise en route et les étapes pouvant être envisagées, la page de documentation doit présenter les étapes à la fois visuelles et contextuelles afin que la première application soit mise en ligne aussi rapidement que 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 inclure un ensemble unifié d'instructions sur la façon de l'installer/de l'activer, de démarrer rapidement, d'utiliser une application après son premier lancement et de la distribuer. 4. Incluez le dépôt electron-api-demos dans la documentation. Le dépôt electron-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 d'ajout de fonctionnalités à votre application afin d'être cohérentes avec la stratégie de contenu d'une source unique de référence. 5. Intégrer des exemples Electron Fiddle dans la documentation. Grâce à cette étape, les nouveaux développeurs pourront voir plus facilement le fonctionnement d'un extrait de 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 "Launch in Fiddle" aux blocs de code.
Temps forts
Période d'examen des candidatures : familiarisez-vous avec la communauté et les personnes avec qui vous souhaitez travailler. Découvrez les guides pour la contribution de la communauté et les bonnes pratiques. Apportez les premières contributions. Engagement communautaire - Découvrez la communauté. Inspectez l'état actuel de la documentation d'Electron. Identifier les points faibles. Semaine 1 : échanger avec les mentors sur les étapes clés du projet et les livrables Semaine 2 – Réviser l'environnement des développeurs et écrire les pages de votre première application Electron Semaine 3 : Réviser l'architecture des applications, ajouter des fonctionnalités à votre application, pages de packaging et de distribution de l'application. Créer une page récapitulative avec une liste de fonctionnalités pouvant être ajoutées à l'application Semaine 4 - Restructurer le répertoire de documentation Semaine 5 - Préparer un modèle d'intégration d'electron-api-demos dans la documentation principale Semaines 6 à 7 – Migrer le dépôt électron-api-demos Semaine 8 - Préparer un modèle d'intégration d'Electron Fiddle dans la documentation principale. Écrivez le premier échantillon. Semaines 9 à 10 – Intégration d'Electron Fiddle dans la documentation principale Semaine 11 – Finalisation de la structure et des pages principales de la documentation après la migration du dépôt electron-api-demos et des exemples Electron Fiddle Semaine 12 – Évaluation des résultats
DÉTAILS DÉTAILLÉS DES ÉTAPES
PÉRIODE D'EXAMEN DES DEMANDES La première partie de la période sera consacrée à la vérification des chaînes de la communauté et du code source, ainsi qu'à la prise de contact avec les personnes dédiées au projet.
La seconde partie sera consacrée à la culture de la contribution en général, en examinant les guides de contribution et les bonnes pratiques. Ce sera l'occasion pour les premières contributions de découvrir le fonctionnement du flux.
LIENS AVEC LA COMMUNAUTÉ
Ce temps sera consacré à un examen plus approfondi du dossier de documentation et de sa feuille de route. Sur la base de ces informations, il sera possible d’identifier les points faibles (par exemple, des pièces incomplètes ou manquantes) qui peuvent être améliorés. 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'aligner sur les jalons attendus et leur livraison dans les délais.
La deuxième semaine sera consacrée à la révision de l'environnement de développement et à l'écriture de votre première page d'application Electron. Pour la page "Environnement de développement", cela inclura la réécriture de la présentation générale et la relecture. Pour la page "Écrire votre première application électronique", nous allons créer un guide par étapes cohérent avec des points de départ et d'arrivée clairs, et supprimer les informations redondantes (comme deux blocs de code similaires dans les sections "Développement d'électrons en résumé" et "Essayer cet exemple").
Livrables: guides d'introduction améliorés et faciles à suivre, pour le démarrage rapide avec les applications Electron.
SEMAINE 3
Cette semaine, nous traiterons des thèmes suivants : 1. Améliorations apportées à la page "Architecture des applications" Exemples : - Réécrire les informations existantes dans la section "Processus principaux et de moteur de rendu" pour les rendre simples et plus intuitifs pour un lecteur novice - Ajouter une représentation visuelle de l'architecture, de la manière dont les processus sont connectés, de la manière dont ils communiquent et de leurs principales différences. Exemples d'éléments visuels: un, deux, trois (basse 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 disposent d'un ensemble unifié d'instructions sur l'installation et l'activation d'une fonctionnalité, ainsi que d'un exemple de fonctionnement. En outre, une page (résumé) répertoriant toutes les fonctionnalités disponibles sera également créée. Les instructions unifiées peuvent se présenter comme suit : - Présentation - Exemple : - Exemple de code - Exemple visuel (si possible)
- de la simplification de la page "Distribution des applications". Par exemple : a. la fusion d'Application Packaging dans le Guide de distribution d'applications ; b. la division des méthodes de distribution en méthodes automatiques et manuelles ; en prenant la forçage électronique comme exemple de distribution automatique ; d. en recueillant des informations sur asar à partir de la page "Application Packaging" et en décrivant la copie des fichiers sources et la création d'archives asar comme exemples de distribution manuelle. #### SEMAINE 4 Cette semaine, nous nous intéresserons à la restructuration du répertoire de documentation. Voici les sujets abordés :
1 - Diviser les guides existants en au moins trois catégories : a. Guide de démarrage rapide b. Apprendre les bases c. Étapes avancées
La catégorie "Démarrage rapide" contient les tutoriels de base (installation, configuration, distribution) permettant de créer une série cohérente de guides qui permettront aux nouveaux utilisateurs de démarrer 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. Conditions préalables 2. Installez Electron 3. Créer une application de base 4. Empaqueter/Distribuer l'application
À l'issue de la section de démarrage rapide, l'utilisateur connaîtra les principes de base du fonctionnement des applications Electron et disposera d'une application Electron distribuée et fonctionnelle.
La catégorie "Découvrir les principes de base" contient les guides destinés à renforcer les connaissances sur Electron et à étendre l'application créée dans les sections du guide de démarrage rapide. Ces guides incluent : - Architecture des applications - Ajouter des fonctionnalités à votre application - Textes de base et CLI
La catégorie "Étapes avancées" contient des guides plus avancés permettant de configurer et d'ajuster votre application Electron : - Tests et débogage - Accessibilité - Sécurité - Mises à jour
2 - réduire le nombre de pages de documentation. La version actuelle de la documentation comporte un certain degré de chevauchement et d'instructions sans catégorie. Par exemple : - Installation et installation d'Electron dans le cadre de l'écriture de votre première application - Préparation et empaquetage de votre application dans un fichier de la distribution d'applications - Instructions sans catégorie 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 d'Electron et le dépôt source est le premier endroit où ils sont consultés : - Developing Electron - Chromium Development - Développement V8 - Problèmes dans Electron - Correctifs dans Electron - Demandes d'extraction - Structure du répertoire du code source - Tests - Style de codage
L'objectif principal de cette réduction est de se débarrasser d'un nombre oppressant de guides disponibles, en reliant les éléments d'informations dispersés du puzzle et en offrant aux nouveaux arrivants une version plus structurée, facile à parcourir et conviviale de la documentation d'Electron.
SEMAINES 5 – 7
La semaine 5 sera consacrée à la préparation d'un modèle (une manière) d'intégrer electron-api-demos à 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. En parcourant chacune des catégories, transférez les exemples de démonstration dans 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 "Erreur en tant qu'enfant des boîtes de dialogue "Utiliser le système") doit être transféré sous son parent.
REMARQUE 1: Des exemples existent à la fois dans electron-api-demos et dans la documentation principale (raccourcis clavier, glisser-déposer, etc.). Dans ce cas, l'exemple de electron-api-demos doit être prioritaire, et l'exemple figurant dans la documentation principale doit être ignoré.
REMARQUE 2: De nombreux exemples dans l'application electron-api-demos comportent un aperçu de la fonctionnalité de démonstration en direct de la fonctionnalité décrite. Cette fonctionnalité sera ignorée jusqu'à l'intégration d'Electron Fiddle les semaines 9 à 10.
- Mettez à jour la page répertoriant toutes les fonctionnalités disponibles (créées au cours 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 dans la documentation principale selon le modèle décrit ci-dessus. À la dernière étape, vous devez supprimer le dépôt electron-api-demos ou le rendre obsolète.
SEMAINES 8 – 10
La semaine 8 sera consacrée à la préparation d'un modèle d'intégration d'Electron Fiddle dans la documentation principale. Cette initiative a déjà été lancée (vérifiez les détails dans le numéro 20442) par les gars d'Electron et des bénévoles de la communauté, mais elle nécessite une bonne finalisation.
Pour les exemples Fiddle, le modèle de base peut se présenter comme suit : 1. Choisissez un exemple dans la documentation principale (le guide de démarrage rapide, par exemple). À ce stade, la documentation doit également contenir des exemples electron-api-demos. 2. Recréer l'exemple dans Electron Fiddle (en utilisant l'exemple de code ou le code source comme point de départ) 3. Enregistrez 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 » comme décrit dans le commentaire initial du problème n° 2848.
Les semaines 9 et 10 seront consacrées à l'intégration d'exemples electron-api-demos (qui ont déjà été convertis en Fiddles) dans la documentation principale selon le 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 exemples Electron Fiddle. Cela inclut : - vérifier que tous les exemples de code existants disposent du bouton "Launch in Fiddle" (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 du travail terminé. Contrôles d'acceptation