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:
- Écosystème ARK
- Rédacteur technique:
- yslcrypto
- Nom du projet:
- Projet 1 : Premiers pas avec le guide de développement de la blockchain de base
- Durée du projet:
- Durée standard (trois mois)
Project description
Voici ce que vous pensez après avoir lu la section "Premiers pas" :
COMMENT CONFIGURER VOTRE ENVIRONNEMENT DE DÉVELOPPEMENT
Installation : je vais vous expliquer plus en détail comment installer les outils de développement. Je fournirais des exemples de code, ainsi que des erreurs courantes et des solutions pour les corriger (nous pourrions ajouter un lien vers une page de dépannage ici).
Mise en route de votre premier réseau d'essai : Première impression: actuellement, il n'est pas évident pour quelqu'un de survoler le sujet et de se lancer rapidement dans la configuration. Voici quelques éléments que je voudrais modifier:
Je vous recommande de définir même des concepts de base comme le testnet.
Je fournirais des exemples de code plus courts: mkdir, cd, etc. Je les regrouperais aussi pour que les lecteurs puissent les copier et les coller plus facilement. Rien n'est trop simple, et tout le monde aime copier-coller.
À la première lecture, je n’ai pas compris ce que les étapes 1 et 2 de la sous-section de démarrage réseau permettent d’accomplir. Cliquer sur les liens et les parcourir demande trop de réflexion. Je pense que nous pouvons clarifier cela sans aller trop loin.
Je voudrais au moins donner une vue d'ensemble du core-container à l'étape 5 (qui est en fait l'étape 4 ?), afin que le lecteur ait une idée de ce qu'il fait sans suivre un lien.
Pour les étapes 3 et 5 (en réalité 4), je vais expliquer les exemples de code plus longs.
Pour la dernière étape, je vais créer un lien vers le plug-in et le fichier installés pour faciliter la vie du lecteur.
Enfin, je modifierais le texte de manière à ne pas avoir plus d'une idée par paragraphe (cela permet de le parcourir facilement). Je voudrais aussi rendre le ton un peu plus amusant / amical et ajouter quelques emoji.
COMMENT SURVEILLER LA CHAÎNE DE BLOQUER
Je simplifierais le premier paragraphe. Je vous expliquerais ce qu'est un plug-in, ce qu'est un délégué (ou au moins vous renverrais vers une explication de base), ce que signifie forger un bloc et vous donnerais un exemple d'événement réseau.
Définir le problème : je donne au lecteur une idée de ce qu'est un nœud complet, j'ajoute un lien vers une explication plus détaillée et je pourrais mieux expliquer les compromis entre un nœud complet et une application externe. Enfin, je voudrais ajouter un lien vers la page de démarrage précédente (comment configurer un testnet et un environnement de développement opérationnels) à la fin de cette sous-section (au cas où le lecteur serait tombé sur cette page en premier).
API Events : il n'est pas clair, d'après la liste des événements disponibles, que nous devrions utiliser "block.applied" pour obtenir ce que nous voulons. Bien que le conseil ci-dessous le clarifie, je préfère vous l'expliquer avant.
Je ne comprends pas ce que "block.applied" renvoie. Je pense qu'il est important de le préciser.
Dans l'exemple de code à la fin, je pense qu'il serait utile de préciser que "block.generatorPublicKey" remplace "block.forger" (dans l'exemple de pseudocode précédent) et que "delegateKey" remplace "delegateWeAreMonitoring". Enfin, pour m'assurer que les exemples de code et de pseudocode sont cohérents, je remplacerais également "delegateKey" et "generatorKey" dans l'instruction if.
Créer le plug-in : je vais vous expliquer ce que signifie "échafaudage" dans ce contexte. Par exemple: Tout comme les échafaudages réels sur un chantier de construction, lorsque nous parlons d'échafaudage dans ce contexte, nous entendons une structure prédéfinie simple pour votre plug-in, sur laquelle vous pouvez construire le véritable échafaudage.
J'ajouterais des exemples de code pour renommer le répertoire et le plug-in, montrer un exemple de package.json et expliquer ce que nous entendons par "ajouter la configuration nécessaire" à plugin.js.
Résumé : je voudrais clarifier les changements. Terminez par une conclusion félicitatoire et quelques autres emoji :)
ENVOYER VOTRE PREMIÈRE TRANSACTION À L'AIDE DU SDK ARK
Premiers pas : j'ajouterais un exemple de code pour permettre à l'utilisateur de créer un répertoire par copier-coller.
Se connecter au testnet : je voudrais expliquer ce qu'est une API REST, au cas où le lecteur ne la connaîtrait pas (ou au moins fournir un lien vers une explication). Je voudrais donner un exemple de lecteur de fichiers JSON et fournir un lien vers celui-ci. J'utiliserais un ton plus amical dans le deuxième conseil (puisque nous demandons au lecteur une faveur).
Modification du Gestionnaire de configuration : je mentionnerais des exemples courants de bugs liés au réseau et je penserais à ajouter un lien vers une section de dépannage.
Configuration des comptes d'envoi et de réception : j'ajouterais un exemple de code pour permettre au lecteur de passer au répertoire de configuration en copiant-collant. Je voudrais ajouter un exemple de code montrant le contenu de delegates.json.
ENVOYER DES TRANSACTIONS À L'AIDE DE LA CLI ARK CORE TESTER
Conditions préalables : J'ajouterais un exemple de code qui montre comment obtenir une copie fonctionnelle du dépôt GitHub ARK Core, et un autre qui déplace le lecteur dans le bon répertoire.
Principes de base : je voudrais clarifier le premier paragraphe pour les personnes qui ne connaissent pas les variables d'environnement de chemin d'accès.
CONCLUSION
Pour conclure, voici quelques notes que j'ai prises en lisant la documentation. Quand nous commençons ce projet ensemble, j'aimerais suivre moi-même le processus pour voir où je trébuche. et utilisez ces connaissances pour simplifier davantage les documents.
Enfin, même si je n'ai examiné qu'un seul projet, je ne pense pas que cela prendra plus de deux semaines. Comme indiqué dans notre correspondance par e-mail, je pense qu'il sera possible de travailler sur plusieurs projets pendant notre collaboration.