Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- Ecosistema ARK
- Redattore tecnico:
- yslcrypto
- Nome del progetto:
- Progetto 1 - Guida introduttiva allo sviluppo di blockchain di base
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Ecco alcune considerazioni dopo aver letto la sezione Inizia:
COME CONFIGURARE L'AMBIENTE DI SVILUPPO
Installazione: qui approfondisco come installare gli strumenti di sviluppo. Fornirò esempi di codice, oltre agli errori comuni e alle relative correzioni (qui potremmo inserire un link a una pagina di risoluzione dei problemi).
Avvio della prima testnet: Prima impressione: al momento è piuttosto complicato per chi sta solo dando un'occhiata e vuole eseguire la configurazione rapidamente. Ecco alcune cose che cambierei:
Ti consiglio di definire anche concetti di base come la testnet.
Fornirei esempi di codice più brevi: mkdir, cd e così via. Li raggrupperei anche in modo che i lettori possano copiarli e incollarli più facilmente. Niente è troppo semplice e a tutti piace copiare e incollare.
Alla prima lettura, non mi è chiaro cosa viene ottenuto con i passaggi 1 e 2 della sottosezione relativa all'avvio di rete. Fare clic sui link e selezionarli richiede troppo tempo. Penso che possiamo chiarire ulteriormente la questione senza addentrarci troppo nei dettagli.
Fornirei almeno una panoramica generale di core-container nel passaggio 5 (che penso sia in realtà il passaggio 4?) in modo che il lettore abbia un'idea di cosa sta facendo senza seguire un link.
Per i passaggi 3 e 5 (in realtà 4), spiegherò gli esempi di codice più lunghi.
Per il passaggio finale, ti consiglio di inserire il link al plug-in e al file installati per semplificare la vita al lettore.
Infine, modificherei il testo in modo che non ci sia più di un'idea per paragrafo (in modo da poterlo leggere facilmente). Inoltre, renderei il tono un po' più amichevole e divertente e aggiungerei un paio di emoji.
COME MONITORARE LA BLOCKCHAIN
Semplificherei il primo paragrafo. Spiegherò che cos'è un plug-in, che cosa fa un delegato (o almeno il link a una spiegazione dei primi principi), il significato di "creazione di un blocco" e fornirò un esempio di evento di rete.
Definisci il problema: Fornisci al lettore un'idea di cosa sia un nodo completo, inserisci un link a una spiegazione più dettagliata e illustra meglio i compromessi tra un nodo completo e un'applicazione esterna. Infine, alla fine di questa sottosezione, ho inserito un link alla pagina precedente relativa all'utilizzo iniziale (come configurare una testnet e un ambiente di sviluppo funzionanti) nel caso in cui il lettore abbia trovato per la prima volta questa pagina.
L'API Events: dall'elenco degli eventi disponibili non è chiaro che dobbiamo utilizzare "block.applied" per ottenere ciò che vogliamo. Anche se il suggerimento di seguito lo chiarisce, vorrei spiegarlo prima.
Non mi è chiaro cosa restituisce "block.applied". Penso sia importante chiarire questo punto.
Nell'esempio di codice alla fine, penso che sarebbe utile chiarire che "block.generatorPublicKey" sostituisce "block.forger" (nell'esempio precedente di pseudocodice) e che "delegateKey" sostituisce "delegateWeAreMonitoring". Infine, per garantire che gli esempi di codice e pseudocodice siano coerenti, sostituirei anche "delegateKey" e "ifgenerato interessato" nella
Creare il plug-in: spiegherò cosa significa scaffolding in questo contesto. Ad esempio: proprio come le impalcature reali in un cantiere, quando parliamo di impalcatura in questo contesto intendiamo una semplice struttura predefinita per il tuo plug-in, su cui puoi costruire quella reale.
Aggiungerei esempi di codice per rinominare la directory e il plug-in, mostrare un esempio di package.json e spiegare cosa intendiamo per "aggiunta della configurazione necessaria" a plugin.js.
Riassumendo: vorrei chiarire quali sono le modifiche. E finisci con un finale di congratulazioni e qualche altra emoji :)
COME INVIARE LA PRIMA TRANSAZIONE CON l'SDK ARK
Per iniziare: aggiungerei un esempio di codice per consentire all'utente di creare una nuova directory con il copia e incolla.
Connettiti a Testnet: Fornisci una spiegazione di cosa sia un'API REST, nel caso in cui il lettore non la conosca (o almeno fornisci un link a una spiegazione). Indicherei un link a un esempio di visualizzatore JSON. Userei un tono più amichevole nel secondo Suggerimento (dato che chiediamo un favore al lettore).
Modifica di Config Manager: fornisci esempi comuni di bug relativi alla rete e valuta la possibilità di inserire un link a una sezione per la risoluzione dei problemi.
Configura gli account di invio e ricezione: aggiungerei un esempio di codice per consentire al lettore di passare alla directory di configurazione con copia e incolla. Aggiungerei un esempio di codice che mostri i contenuti di delegates.json.
COME INVIARE TRANSAZIONI UTILIZZANDO L'INTERFACCIA A RIGA DI COMANDO DI ARK CORE TESTER
Prerequisiti: aggiungerei un esempio di codice che mostri come ottenere una copia funzionante del repository GitHub di ARK Core e un altro che indirizzi il lettore alla directory corretta.
Nozioni di base: ho reso più chiaro il primo paragrafo per chi non ha familiarità con le variabili d'ambiente del percorso.
CONCLUSIONE
Per concludere, queste sono solo alcune brevi note che ho preso mentre leggevo la documentazione. Quando inizieremo il progetto insieme, vorrei seguire personalmente la procedura per capire dove sbaglio. e utilizza queste conoscenze per semplificare ulteriormente i documenti.
Infine, anche se ho esaminato solo un progetto, non credo che la procedura debba richiedere più di un paio di settimane. Come discusso nella nostra corrispondenza via email, penso che sarebbe possibile lavorare a diversi progetti durante il nostro periodo di collaborazione.