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

Пример структуры руководства

warning

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

осторожно

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

Введение​

Заголовок "Введение" должен быть H2: ## Введение

Этот раздел предназначен для того, чтобы объяснить контекст этого руководства и почему это важно, что мы собираемся создать и изучить в этом руководстве.

  • Опишите этот раздел так, как будто вы объясняете его 5-летнему ребенку (ELI5)
  • Объясните все максимум в 5–6 строках.

Например:

Смарт-контракт - это просто компьютерная программа, которая работает на блокчейне TON или, точнее, на его TVM (TON Virtual Machine). Контракт состоит из кода (скомпилированных инструкций TVM) и данных (постоянного состояния), которые хранятся по некоторому адресу в TON.

Требования​

Заголовок "Условия" должен быть H2: ## Условия

В этом разделе вы должны объяснить о любых необходимых предварительных знаниях или о любых существующих руководствах, которые необходимо выполнить в первую очередь. Любые необходимые токены — укажите их здесь.

Например:

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

Требования​

Заголовок "Требования" должен быть H2: ## Требования

ДОПОЛНИТЕЛЬНО : вставьте любой видеоконтент в этот раздел, если он есть в вашем руководстве.

Любая технология, которую необходимо установить перед началом руководства и которую руководство не будет рассматривать (TON Wallet Extension, node, и т. д.). Не перечисляйте пакеты, которые будут установлены во время руководства.

Например:

  • В этом руководстве нам понадобится расширение TON Wallet; установите его ЗДЕСЬ.
  • Убедитесь, что у вас установлен NodeJS 12.0.1+.

Основная часть руководства​

  • Пожалуйста, не используйте "Основная часть руководства" в качестве заголовка, используйте собственный заголовок, который соответствует материалу.
    • "Начало работы" приемлемо, если вы не можете придумать ничего другого 😉
  • Добавьте любой текст, который поможет читателям разобраться в вашем учебном пособии, и не забудьте проверить его на орфографию и грамматику, прежде чем отправлять учебное пособие.
    • Grammarly -- хорошая бесплатная программа, которая поможет вам избежать грамматических ошибок.

Ключевые моменты​

  • Не используйте "Основную часть руководства" в качестве заголовка!

  • Все подзаголовки оставляйте на уровне H3, не используйте H4 или ниже.

    • В синтаксисе Markdown для заголовков H2 используются два хэш-знака: ##
    • Три хэш-знака используются для заголовков H3: ###

  • Добавляйте только необходимые комментарии к блокам кода. Не добавляйте комментарии в стиле # к блокам кода ввода терминала.

  • Добавляйте все соответствующие блоки кода:

    • Синтаксис Markdown для блоков кода состоит из трех обратных кавычек в начале и конце блока кода. Также убедитесь, что перед и после обратных кавычек во всех блоках кода есть новая строка. Например:​

      `js
      сonst testVariable = 'some string';
      someFunctionCall();
      `

    • Все блоки кода должны иметь тип подсветки синтаксиса. Используйте ``\`text, если вы не уверены.

    • \\\`text должен использоваться для вывода терминала, команд терминала и обычного текста.

    • `javascript или `js можно использовать для любого кода JavaScript.

    • `typescript или `ts можно использовать для любого кода TypeScript.

    • \\\`jsx для кода ReactJS.

    • \\cpp для кода Func.

    • Используйте \\\`graphql при подсветки синтаксиса GraphQL.

    • Используйте `json при подсветке допустимого JSON. (Для недопустимых примеров JSON используйте `text.)

    • \\\`bash следует использовать только в тех блоках кода, где вам нужны комментарии в стиле #. Это нужно делать осторожно, потому что во многих ситуациях символ # будет отображаться как заголовок markdown. Как правило, это повлияет на оглавление.

  • Не используйте предварительно отформатированный текст для выделения текста; вместо этого используйте только жирный шрифт или курсив.

  • Добавьте изображения или блоки кода, чтобы отразить ожидаемый результат работы терминала.

  • При написании руководства используйте подход, основанный на ошибках. Добавьте распространенные ошибки и шаги по устранению неполадок. Например:

Не удается подключиться к Testnet из-за ошибки при выполнении команды node deploy:testnet.

Давайте рассмотрим некоторые распространенные причины:

  • Убедитесь, что у вас достаточно средств в сгенерированном тестовом кошельке в .env. Если нет, добавьте несколько тестовых монет из Faucet Giver.
  • Если у вас все еще возникает та же проблема, обратитесь за помощью к разработчикам в чат разработчиков.

Заключение​

Заголовок "Заключение" должен быть H2: ## Заключение

В этом разделе следует обобщить то, что было изучено в руководстве, закрепить ключевые моменты и поздравить обучающегося с завершением руководства. Используйте максимум 5–6 строк. Например:

Мы создали простой новый контракт FunC с функциональностью счетчика. Затем мы построили и развернули его on-chain и, наконец, взаимодействовали с ним, вызвав геттер и отправив сообщение.

Пожалуйста, помните, что этот код не предназначен для производственной среды; есть еще несколько вещей, которые следует учесть, если вы хотите развернуть это в основной сети, например, отключение метода передачи, если токен размещается на рынке, и т. д.

См. также​

Заголовок "Смотрите также" должен быть H2: ## См. также

Используйте этот раздел, чтобы объяснить, что можно сделать дальше после этого руководства, чтобы продолжить обучение. Не стесняйтесь добавлять рекомендуемые проекты и статьи, относящиеся к этому руководству. Если вы работаете над другими расширенными руководствами, вы можете кратко упомянуть их здесь. Обычно здесь размещаются только связанные страницы с docs.ton.org.

Об авторе (Необязательно)​

Заголовок "Об авторе" должен быть H2: ## Об авторе

Должен быть коротким. Не более одной-двух строк. Вы можете указать ссылку на свой профиль на GitHub или в Telegram. Пожалуйста, не добавляйте сюда свой LinkedIn или Twitter.

Ссылки (необязательно)​

Заголовок "Ссылки" должен быть H2: ## Ссылки

Этот раздел должен присутствовать, если при написании этого руководства вы использовали какую-либо помощь из других документов, репозиториев GitHub или уже существующих руководств.

Укажите источники, добавив их имя и ссылку на документ, когда это возможно.

Если это не цифровой документ, включите ISBN или другую форму ссылки.