Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.
Resumo do projeto
- Organização de código aberto:
- Ecossistema ARK
- Redator técnico:
- yslcrypto
- Nome do projeto:
- Projeto 1: Introdução ao guia de desenvolvimento de blockchain básico
- Duração do projeto:
- Duração padrão (três meses)
Project description
Confira algumas ideias depois de ler a seção "Comece agora":
COMO CONFIGURAR SEU AMBIENTE DE DESENVOLVIMENTO
Instalação: Eu iria me aprofundar em como instalar as ferramentas de desenvolvimento aqui. Eu forneceria exemplos de código, além de erros comuns e como corrigi-los (poderíamos vincular a uma página de solução de problemas aqui).
Como criar sua primeira testnet: Primeira impressão: no momento, é muito confuso para alguém que está apenas lendo e quer configurar rapidamente. Veja algumas coisas que eu mudaria:
Eu consideraria definir até mesmo conceitos básicos, como a testnet.
Eu forneceria exemplos de código mais curtos: mkdir, cd, etc. Também os agruparia para que os leitores possam copiar e colar com mais facilidade. Nada é simples demais, e todo mundo adora copiar e colar.
Na primeira leitura, não está claro para mim o que as etapas 1 e 2 da subseção "Inicialização de rede" fazem. Clicar e passar pelos links exige muita reflexão. Acho que podemos deixar isso muito mais claro sem entrar em detalhes.
Eu daria pelo menos uma visão geral de alto nível do contêiner principal na etapa 5 (que acho que é a etapa 4), para que o leitor tenha alguma ideia do que está fazendo sem precisar clicar em um link.
Para as etapas 3 e 5 (realmente 4), explicaria os exemplos de código mais longos.
Na etapa final, eu vincularia o plug-in e o arquivo instalados para facilitar a vida do leitor.
Por fim, eu editaria de uma forma que não haja mais de uma ideia por parágrafo (permite uma leitura fácil). Também deixaria o tom um pouco mais divertido / amigável e adicionaria alguns emojis.
COMO MONITORAR A CADEIA DE BLOCOS
Eu simplificaria o primeiro parágrafo. Eu explicaria o que é um plug-in, o que um delegado faz (ou, pelo menos, um link para uma explicação básica), o que significa forjar um bloco e dar um exemplo de um evento de rede.
Definir o problema: Eu daria ao leitor uma ideia do que é um nó completo, um link para uma explicação mais detalhada e explicaria melhor as compensações entre um nó completo e um aplicativo externo. Por fim, vincularei à página de introdução anterior, como configurar uma rede de testes funcional e um ambiente de desenvolvimento, ao final desta subseção (caso o leitor tenha se deparado com essa página primeiro).
A API Events: Não está claro, na lista de eventos disponíveis, que devemos usar "block.applied" para conseguir o que queremos. Embora a dica abaixo esclareça isso, eu explicaria antes.
Não está claro para mim o que "block.applied" retorna. Acho que é importante deixar isso bem claro.
No exemplo de código no final, acho que seria útil deixar claro que "block.generatorPublicKey" substitui "block.forger" (no exemplo de pseudocódigo anterior) e que "delegateKey" substitui "delegateWeAreMonitoring". Por fim, para garantir que os exemplos de código e pseudocódigo sejam consistentes, também trocaria "delegateKey" e "generatorKey" na instrução "if".
Criação do plug-in: Eu explicaria o que significa a estrutura neste contexto. Algo como: Assim como em um canteiro de obras, quando falamos sobre estrutura de trabalho nesse contexto, nos referimos a uma estrutura pré-criada simples para o plug-in, em cima da qual você pode criar o real.
Eu adicionaria exemplos de código para renomear o diretório e o plug-in, mostrar um exemplo de package.json e explicar o que significa "adicionar a configuração necessária" ao plugin.js.
Juntando tudo: eu deixaria mais claro quais são as mudanças. E termine com uma mensagem de parabéns e mais alguns emojis :)
COMO ENVIAR SUA PRIMEIRA TRANSAÇÃO USANDO O SDK DO ARK
Introdução: Eu adicionaria um exemplo de código para permitir que o usuário crie um novo diretório com o recurso de copiar e colar.
Conectar à Testnet: eu explicaria o que é uma API REST, caso o leitor não esteja familiarizado (ou, pelo menos, vincularia a uma explicação). Vou dar um exemplo de visualizador JSON e linkar para ele. Eu usaria um tom mais amigável na segunda dica, já que estamos pedindo um favor ao leitor.
Alteração do Config Manager: mencione exemplos comuns de bugs relacionados à rede e inclua links para uma seção de solução de problemas.
Configurar contas de envio e recebimento: Eu adicionaria um exemplo de código para permitir que o leitor mude para o diretório de configuração com o recurso de copiar e colar. Adicionaria um exemplo de código que mostra o conteúdo de delegates.json.
COMO ENVIAR TRANSAÇÕES USANDO A CLI DO ARK CORE TESTER
Pré-requisitos: Adicionei um exemplo de código que mostra como conseguir uma cópia funcional do repositório do GitHub do ARK Core e outro que move o leitor para o diretório correto.
Noções básicas: Eu deixaria o primeiro parágrafo mais claro para quem não conhece as variáveis de ambiente de caminho.
CONCLUSÃO
Para concluir, estas são apenas algumas notas breves que fiz enquanto lia a documentação. Quando começarmos o projeto juntos, eu gostaria de passar pelo processo por conta própria para ver onde eu erraria. E use esse conhecimento para simplificar ainda mais os documentos.
Por fim, embora eu tenha feito apenas um projeto aqui, não acho que isso levará mais do que algumas semanas. Conforme discutido em nosso e-mail, acho que seria possível trabalhar em vários projetos durante nosso tempo juntos.