Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- Ecosistema de ARK
- Redactor técnico:
- yslcrypto
- Nombre del proyecto:
- Proyecto 1: Guía de introducción al desarrollo de cadenas de bloques
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Estas son algunas ideas después de leer la sección Introducción:
CÓMO CONFIGURAR TU ENTORNO DE DESARROLLO
Instalación: Aquí, explicaré en detalle cómo instalar las herramientas de desarrollo. Proporcionaría muestras de código, junto con errores comunes y cómo corregirlos (podríamos vincular a una página de solución de problemas aquí).
Cómo iniciar tu primera red de prueba: Primera impresión: en este momento, es bastante confuso para alguien que solo está leyendo y quiere configurarse rápidamente. Estos son algunos cambios que haría:
Te recomiendo que definas incluso los conceptos básicos, como testnet.
Proporcionaría muestras de código más cortas: mkdir, cd, etc. También las agruparía para que los lectores puedan copiarlas y pegarlas con mayor facilidad. Nada es demasiado simple, y a todos les encanta copiar y pegar.
En la primera lectura, no tengo claro qué se logra con los pasos 1 y 2 de la subsección de inicio de red. Hacer clic y recorrer los vínculos lleva demasiado tiempo. Creo que podemos explicar esto de forma más clara sin entrar en detalles.
Al menos, le daría una descripción general de alto nivel del contenedor principal en el paso 5 (¿cuál creo que es realmente el paso 4?), para que el lector tenga algo de intuición de lo que está haciendo sin seguir un vínculo.
Para los pasos 3 y 5 (en realidad, 4), explicaré las muestras de código más largas.
Para el paso final, vincularía el complemento y el archivo instalados para facilitarle la vida al lector.
Por último, editaría de una manera que garantice que no haya más de una idea por párrafo (permite una lectura rápida). También haría que el tono fuera un poco más divertido o amigable y agregaría un par de emojis.
CÓMO SUPERVISAR LA CADENA DE BLOQUES
Simplificaría el primer párrafo. Explicaría qué es un complemento, qué hace un delegado (o, al menos, vincularía a una explicación de los principios básicos), qué significa forjar un bloque y daría un ejemplo de un evento de red.
Define el problema: Te daría al lector una idea de lo que es un nodo completo, le vincularía a una explicación más detallada y le explicaría mejor las compensaciones entre un nodo completo y una aplicación externa. Por último, incluiría un vínculo a la página de introducción anterior, sobre cómo configurar una red de prueba y un entorno de desarrollo que funcionen, al final de esta subsección (en caso de que el lector se encuentre primero con esta página).
La API de eventos: No está claro, en la lista de eventos disponibles, que debemos usar "block.applied" para obtener lo que queremos. Aunque la siguiente sugerencia lo explica con más claridad, me gustaría explicarte esto antes.
No tengo claro qué muestra "block.applied". Creo que es importante dejar esto muy claro.
En el ejemplo de código al final, creo que sería útil aclarar que "block.generatorPublicKey" reemplaza a "block.forger" (en el ejemplo de pseudocódigo anterior) y que "delegateKey" reemplaza a "delegateWeAreMonitoring". Por último, para garantizar que los ejemplos de código y pseudocódigo sean coherentes, también intercambiaría "delegateKey" y "generatorKey" en la sentencia if.
Creación del complemento: explicaría qué significa andamiaje en este contexto. Algo como: Al igual que el andamiaje real en un sitio de construcción, cuando hablamos de andamiaje en este contexto, nos referimos a una estructura precompilada simple para tu complemento, sobre la que puedes compilar el real.
Agregaría muestras de código para cambiar el nombre del directorio y el complemento, mostrar un ejemplo de package.json y explicar qué queremos decir con "agregar la configuración necesaria" a plugin.js.
Resumen: Me gustaría que aclararas cuáles son los cambios. Y termina con un mensaje de felicitación y algunos emojis más :)
CÓMO ENVIAR TU PRIMERA TRANSACCIÓN CON EL SDK DE ARK
Primeros pasos: Agregaría una muestra de código para permitir que el usuario cree un directorio nuevo con copiar y pegar.
Conectarse a Testnet: explicaría qué es una API de REST, en caso de que el lector no esté familiarizado (o, al menos, vincularía a una explicación). Te daré un ejemplo de visor de JSON y te vincularé a él. Usaría un tono más amigable en el segundo SUGERENCIA (ya que le estamos pidiendo al lector un favor).
Cambio del Administrador de configuración: Te mencionaría ejemplos comunes de errores relacionados con la red y consideraría vincular a una sección de solución de problemas.
Configuración de cuentas de envío y recepción: Agregaría un ejemplo de código para permitir que el lector cambie al directorio de configuración con copiar y pegar. Agregaría una muestra de código en la que se muestre el contenido de delegates.json.
CÓMO ENVIAR TRANSACCIONES CON LA CLI DE ARK CORE TESTER
Requisitos previos: Agregaría un ejemplo de código que muestre cómo obtener una copia funcional del repositorio de GitHub de ARK Core y otro que dirija al lector al directorio correcto.
Conceptos básicos: Te recomiendo que el primer párrafo sea más claro para quienes no estén familiarizados con las variables de entorno de ruta.
CONCLUSIÓN
Para concluir, estas son solo algunas notas breves que tomé mientras leía la documentación. Cuando comencemos el proyecto juntos, me gustaría pasar por el proceso para ver dónde me equivoco. Y usa ese conocimiento para simplificar aún más los documentos.
Por último, si bien solo analicé un proyecto, no creo que esto demore más de un par de semanas. Como conversamos en nuestra correspondencia por correo electrónico, creo que sería posible trabajar en varios proyectos durante nuestro tiempo juntos.