Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- ARK-System
- Technischer Redakteur:
- yslcrypto
- Projektname:
- Projekt 1 – Leitfaden für den Einstieg in die Blockchain-Entwicklung
- Projektdauer:
- Standardlänge (3 Monate)
Projektbeschreibung
Hier sind einige Gedanken, die mir nach dem Lesen des Abschnitts „Einstieg“ gekommen sind:
So richten Sie Ihre Entwicklerumgebung ein
Installation: Hier würde ich näher auf die Installation der Entwicklungstools eingehen. Ich würde Codebeispiele sowie häufige Fehler und deren Behebung bereitstellen. Wir könnten hier einen Link zu einer Seite zur Fehlerbehebung einfügen.
Erstes Testnet einrichten: Erster Eindruck: Derzeit ist es für Nutzer, die nur einen kurzen Blick darauf werfen und schnell loslegen möchten, ziemlich verwirrend. Hier sind einige Dinge, die ich ändern würde:
Ich würde darüber nachdenken, sogar grundlegende Konzepte wie testnet zu definieren.
Ich würde mehr kürzere Codebeispiele angeben: mkdir, cd usw. Außerdem würde ich sie gruppieren, damit Leser sie leichter kopieren und einfügen können. Nichts ist zu einfach und jeder liebt Kopieren und Einfügen.
Beim ersten Lesen ist mir nicht klar, was mit Schritt 1 und 2 des Abschnitts zum Netzwerkstart erreicht wird. Das Klicken auf die Links und das Durchgehen der Seiten erfordert zu viel Nachdenken. Ich denke, wir können das viel klarer formulieren, ohne zu sehr ins Detail zu gehen.
Ich würde in Schritt 5 (der eigentlich Schritt 4 ist) zumindest einen allgemeinen Überblick über den Core-Container geben, damit der Leser eine ungefähre Vorstellung davon hat, was er tut, ohne einem Link zu folgen.
Bei den Schritten 3 und 5 (eigentlich 4) würde ich die längeren Codebeispiele erklären.
Als letzten Schritt würde ich einen Link zum installierten Plug-in und zur Datei hinzufügen, um es dem Leser leichter zu machen.
Schließlich würde ich den Text so bearbeiten, dass es nicht mehr als eine Idee pro Absatz gibt (ermöglicht ein schnelles Überfliegen). Außerdem würde ich den Ton ein wenig unterhaltsamer / freundlicher gestalten und ein paar Emojis hinzufügen.
BLOCKCHAIN ÜBERWACHEN
Ich würde den ersten Absatz vereinfachen. Ich würde erklären, was ein Plug-in ist, was ein Delegate tut (oder zumindest einen Link zu einer grundlegenden Erklärung angeben), was das Erstellen eines Blocks bedeutet, und ein Beispiel für ein Netzwerkereignis geben.
Problem definieren: Ich würde den Lesern einen Eindruck davon vermitteln, was ein Full-Node ist, einen Link zu einer ausführlicheren Erklärung hinzufügen und die Vor- und Nachteile eines Full-Nodes und einer externen Anwendung besser erklären. Abschließend würde ich am Ende dieses Unterabschnitts einen Link auf die vorherige Seite „Erste Schritte“ einfügen, in der ein funktionierendes Testnet und eine Entwicklungsumgebung eingerichtet wird (für den Fall, dass der Leser zuerst auf diese Seite gestoßen ist).
Events API: Aus der Liste der verfügbaren Ereignisse geht nicht hervor, dass wir „block.applied“ verwenden sollten, um das gewünschte Ergebnis zu erhalten. Der folgende Tipp verdeutlicht es zwar, ich würde das aber vorher noch erklären.
Mir ist nicht klar, was „block.applied“ zurückgibt. Ich finde es wichtig, das klarzustellen.
Im Codebeispiel am Ende sollte klargestellt werden, dass „block.generatorPublicKey“ für „block.forger“ (im vorherigen Pseudocodebeispiel) steht und dass „delegateKey“ für „delegateWeAreMonitoring“ steht. Damit Code- und Pseudocodebeispiele konsistent sind, würde ich außerdem „delegateKey“ und „generatorKey“ in der If-Bedingung tauschen.
Plugin erstellen: Ich erkläre, was in diesem Zusammenhang „Scaffolding“ bedeutet. Beispiel:
Ich würde Codebeispiele hinzufügen, um das Verzeichnis und das Plug-in umzubenennen, ein Beispiel für package.json und erklären, was wir unter „plugin.js“ mit „die erforderliche Konfiguration hinzufügen“ meinen.
Zusammenfassend: Ich würde die Änderungen klarer formulieren. Und zum Schluss kommen noch ein paar Emojis.
ERSTE TRANSAKTION MIT DEM ARK SDK SENDEN
Erste Schritte: Ich würde ein Codebeispiel hinzufügen, damit der Nutzer ein neues Verzeichnis per Kopieren und Einfügen erstellen kann.
Verbindung zum Testnet herstellen: Ich würde erklären, was eine REST API ist, falls der Leser nicht vertraut ist (oder zumindest einen Link zu einer Erklärung angeben). Ich würde ein Beispiel für einen JSON-Viewer geben und einen Link dazu angeben. Im zweiten TIPP würde ich einen freundlicheren Tonfall verwenden (da wir den Leser um einen Gefallen bitten).
Config Manager ändern: Ich würde gängige Beispiele für netzwerkbezogene Fehler erwähnen und einen Link zu einem Abschnitt zur Fehlerbehebung in Betracht ziehen.
Sende- und Empfangskonten einrichten: Ich würde ein Codebeispiel hinzufügen, damit der Leser das Konfigurationsverzeichnis per Kopieren und Einfügen wechseln kann. Ich würde ein Codebeispiel mit dem Inhalt von „delegates.json“ hinzufügen.
TRANSAKTIONEN MIT DER ARK CORE TESTER CLI SENDEN
Voraussetzungen: Ich würde ein Codebeispiel hinzufügen, das zeigt, wie Sie eine funktionierende Kopie des ARK Core-GitHub-Repositories erhalten, und ein weiteres, das den Leser in das richtige Verzeichnis verschiebt.
Grundlagen: Ich würde den ersten Absatz für diejenigen klarer formulieren, die mit Pfad-Umgebungsvariablen nicht vertraut sind.
ZUSAMMENFASSUNG
Abschließend sind hier einige kurze Notizen, die ich mir beim Lesen der Dokumentation gemacht habe. Wenn wir gemeinsam mit dem Projekt beginnen, möchte ich den Prozess selbst durchgehen, um zu sehen, wo ich scheitere. Und dieses Wissen nutzen, um die Dokumente weiter zu vereinfachen.
Ich habe hier nur ein Projekt durchgegangen, aber ich denke, dass es nicht länger als ein paar Wochen dauern wird. Wie in unserer E-Mail-Korrespondenz besprochen, wäre es möglich, während unserer Zusammenarbeit an mehreren Projekten zu arbeiten.