Перейти к основному содержимому

Принципы хорошего руководства

warning

Эта страница переведена сообществом на русский язык, но нуждается в улучшениях. Если вы хотите принять участие в переводе свяжитесь с @alexgton.

осторожно

Эта страница устарела и скоро будет удалена. См. Как внести вклад.

Оригинальный комментарий к этим принципам от talkol:

Вот краткое изложение этих пунктов для новых участников.

Принципы​

  1. Весь процесс должен выполняться на стороне пользователя. Не должно быть никаких сторонних сервисов. Вам нужно сделать все так, чтобы пользователь мог просто клонировать репозиторий и сразу же запустить его.

  2. README должен быть ОЧЕНЬ подробным. Не предполагайте, что пользователи что-то знают. Если руководство требует этого, оно также должно объяснять, как установить компилятор FunC или Lite-клиент на ваше устройство. Вы можете скопировать эти части из других руководств в этой документации.

  3. Было бы хорошо, если бы репозиторий включал весь исходный код используемых контрактов, чтобы пользователи могли вносить незначительные изменения в стандартный код. Например, смарт-контракт жетона позволяет пользователям экспериментировать с пользовательским поведением.

  4. Если это возможно, создайте удобный интерфейс, который позволит пользователям развертывать или запускать проект без необходимости загрузки кода или какой-либо настройки. Обратите внимание, что это все еще должно быть автономным и обслуживаться из GitHub Pages для запуска на 100% клиентской части, на устройстве пользователя. Пример: https://minter.ton.org/

  5. Объясните пользователям, что означает каждый выбор поля, и объясните лучшие практики.

  6. Объясните все, что нужно знать о безопасности. Вы должны объяснить достаточно, чтобы разработчики не совершали ошибок и не создавали опасные смарт-контракты/ботов/веб-сайты — вы обучаете их лучшим практикам безопасности.

  7. В идеале репозиторий должен включать хорошо написанные тесты, которые показывают читателю, как лучше всего реализовать их в контексте вашего руководства.

  8. Репозиторий должен иметь собственные простые для понимания скрипты компиляции/развертывания. Пользователь должен иметь возможность просто npm install и использовать их.

  9. Иногда достаточно репозитория GitHub, и нет необходимости писать полную статью. Просто README со всем кодом, который вам нужен в репозитории. В этом случае код должен быть хорошо прокомментирован, чтобы пользователь мог легко его прочитать и понять.