На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Экосистема АРК
- Технический писатель:
- yslcrypto
- Название проекта:
- Проект 1. Руководство по началу работы с базовым руководством по разработке блокчейна
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Вот некоторые мысли после прочтения раздела «Начало работы»:
КАК НАСТРОИТЬ СРЕДУ РАЗРАБОТКИ
Установка: здесь я бы углубился в установку инструментов разработки. Я бы предоставил примеры кода, а также распространённые ошибки и способы их исправления (мы могли бы дать ссылку на страницу устранения неполадок здесь).
Развертывание вашей первой тестовой сети: Первое впечатление: сейчас это довольно сбивает с толку тех, кто просто просматривает информацию и хочет быстро настроиться. Вот некоторые вещи, которые я бы изменил:
Я бы рассмотрел определение даже базовых понятий, таких как testnet.
Я бы предоставил более короткие примеры кода: mkdir, cd и т. д. Я бы также сгруппировал их вместе, чтобы читателям было легче копировать и вставлять. Нет ничего слишком простого, и все любят копировать и вставлять.
При первом прочтении мне неясно, чего достигают шаги 1 и 2 подраздела сетевой загрузки. Нажатие и переход по ссылкам требует слишком много размышлений. Я думаю, мы можем внести это намного яснее, не углубляясь слишком далеко в суть вопроса.
Я бы, по крайней мере, дал общий обзор основного контейнера на шаге 5 (который, как мне кажется, на самом деле является шагом 4?), чтобы читатель имел некоторое представление о том, что он делает, не переходя по ссылке.
Для шагов 3 и 5 (на самом деле 4) я бы объяснил более длинные примеры кода.
На последнем этапе я бы дал ссылку на установленный плагин и файл, чтобы облегчить жизнь читателю.
Наконец, я бы отредактировал так, чтобы в каждом абзаце было не более одной идеи (чтобы можно было легко просматривать текст). Я бы также сделал тон немного веселее/дружелюбнее и добавил пару смайлов.
КАК МОНИТОРИРОВАТЬ БЛОКЧЕЙН
Я бы упростил первый абзац. Я бы объяснил, что такое плагин, что делает делегат (или, по крайней мере, дал бы ссылку на объяснение основных принципов), что означает создание блока, и привел бы пример сетевого события.
Определите проблему: я бы дал читателю представление о том, что такое полный узел, дал бы ссылку на более подробное объяснение и лучше объяснил бы компромиссы между полным узлом и внешним приложением. Наконец, я хотел бы дать ссылку на предыдущую страницу начала работы — как настроить рабочую тестовую сеть и среду разработки — в конце этого подраздела (на случай, если читатель первым наткнулся на эту страницу).
API событий: из списка доступных событий неясно, следует ли нам использовать «block.applied», чтобы получить то, что мы хотим. Хотя приведенный ниже совет проясняет ситуацию, я бы объяснил это раньше.
Мне неясно, что возвращает «block.applied». Я думаю, что важно прояснить это.
В примере кода в конце, я думаю, было бы полезно прояснить, что «block.generatorPublicKey» заменяет «block.forger» (в предыдущем примере псевдокода), а «delegateKey» заменяет «delegateWeAreMonitoring». Наконец, чтобы обеспечить согласованность образцов кода и псевдокода, я бы также поменял местами «delegateKey» и «generatorKey» в операторе if.
Создание плагина: я бы объяснил, что такое леса в данном контексте. Что-то вроде: Как и в случае с настоящими лесами на строительной площадке, когда мы говорим о строительных лесах в этом контексте, мы имеем в виду простую заранее созданную структуру для вашего плагина, поверх которой вы можете построить настоящую.
Я бы добавил примеры кода для переименования каталога и плагина, показал пример package.json и объяснил, что мы подразумеваем под «добавлением необходимой конфигурации» в плагин.js.
Связывая это воедино: я бы прояснил, в чем заключаются изменения. И закончим поздравительным финалом и еще несколькими смайликами :)
КАК ОТПРАВИТЬ ПЕРВУЮ ТРАНЗАКЦИЮ С ИСПОЛЬЗОВАНИЕМ ARK SDK
Приступая к работе: я бы добавил пример кода, позволяющий пользователю создать новый каталог с помощью копирования и вставки.
Подключитесь к Testnet: я бы объяснил, что такое REST API, на случай, если читатель незнаком (или хотя бы ссылку на объяснение). Я бы дал ссылку на пример средства просмотра JSON. Во втором СОВЕТЕ я бы использовал более дружелюбный тон (поскольку мы просим читателя об одолжении).
Изменение диспетчера конфигурации: я хотел бы упомянуть распространенные примеры ошибок, связанных с сетью, и рассмотреть возможность ссылки на раздел устранения неполадок.
Настройка учетных записей отправки и получения: я бы добавил пример кода, чтобы позволить читателю перейти в каталог конфигурации с помощью копирования и вставки. Я бы добавил пример кода, показывающий содержимое файла elements.json.
КАК ОТПРАВИТЬ ТРАНЗАКЦИИ С ПОМОЩЬЮ CLI ARK CORE TESTER
Предварительные требования: я бы добавил пример кода, который показывает, как получить рабочую копию репозитория ARK Core GitHub, и другой, который перемещает программу чтения в правильный каталог.
Основы: я бы сделал первый абзац более понятным для тех, кто не знаком с переменными среды пути.
ЗАКЛЮЧЕНИЕ
В заключение, это всего лишь несколько кратких заметок, которые я сделал, читая документацию. Когда мы вместе начнем работу над проектом, я бы хотел сам пройти весь процесс и увидеть, где я спотыкаюсь. И используйте эти знания для дальнейшего упрощения документации.
Наконец, хотя я реализовал здесь только один проект, я не думаю, что это займет больше пары недель. Как обсуждалось в нашей переписке по электронной почте, я думаю, что за время, проведенное вместе, можно было бы поработать над несколькими проектами.