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

Рекомендации по оформлению руководства

warning

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

осторожно

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

Итак, вы решили написать руководство для документации TON?

Мы рады видеть вас среди наших участников! Ознакомьтесь с приведенными ниже рекомендациями, чтобы убедиться, что ваше руководство соответствует стилю и качеству уже существующего контента в TON Docs.

Важно, чтобы вы потратили некоторое время на ознакомление со структурой руководчства и тем, как следует использовать заголовки. Ознакомьтесь с некоторыми из наших уже существующих руководств, а также посмотрите предыдущие Pull Requests, прежде чем отправить свой собственный.

Процесс​

ВАЖНО

Прежде чем начать писать, прочтите приведенные ниже рекомендации! Они помогут вам обеспечить уровень стандартизации и качества, который значительно ускорит процесс проверки.

Кроме того, обязательно ознакомьтесь с примером структуры руководства, который мы предоставили.

  1. Для начала создайте ответвление и клонируйте репозиторий ton-docs на GitHub и создайте новую ветку в локальном репозитории.
  2. Напишите руководство, учитывая качество и читабельность! Ознакомьтесь с существующими руководствами, чтобы понять, к чему следует стремиться.
  3. Когда вы будете готовы отправить его на проверку, откройте Pull Request из своей ветки. Мы будем уведомлены, и начнется процесс проверки:
  4. Пожалуйста, приложите все усилия, чтобы отправить только окончательный вариант вашего руководства. Некоторые опечатки и исправления грамматики приемлемы, но если необходимо внести существенные изменения, прежде чем мы сможем опубликовать руководство, проверка и внесение необходимых изменений займет гораздо больше времени.
  5. После того, как мы рассмотрим вашу заявку и вы внесете все необходимые изменения, мы объединим Pull Request и опубликуем руководство в документации TON. Вскоре после этого мы свяжемся с вами, чтобы договориться об оплате!
  6. После публикации не забудьте продвигать свое руководство в социальных сетях! Сопровождающие документацию могут помочь усилить эту акцию, если вы будете сотрудничать с нами.

Подводя итог, рабочий процесс выглядит следующим образом:

  1. Создайте ответвление и клонируйте репозиторий ton-docs
  2. Напишите и отшлифуйте свое руководство
  3. Отправьте Pull Request на рассмотрение
  4. Внесите необходимые изменения
  5. Учебное пособие объединено и опубликовано
  6. Продвигайте свое учебное пособие в социальных сетях!

Контекст​

Основная проблема с добавлением «THE» перед «TON» заключается в том, что во время разработки документации TON и редакционной политики различные отделы, такие как маркетинг, поставщики и разработчики, присоединились к обсуждению, чтобы писать с заглавной буквы такие слова, как «Блокчейн», «Экосистема» и другие в сочетании с «TON», чтобы создать сильный образ единой системы, сети и бренда. После долгих обсуждений мы пришли к выводу, что для сильного имиджа бренда нам следует создать глоссарий слов и фраз, которые можно писать без «THE» и с заглавной буквы. Если Если это можно сделать с заглавной буквы, то в статье нет необходимости. В настоящее время существует два таких словосочетания: TON Blockchain и TON Ecosystem.

Что касается других названий модулей TON, таких как TON Connect, TON SDK, TON Grants и т. д., то это зависит от контекста. Мы применяем правило заглавных букв, но проявляем гибкость в отношении артикля. Если имя компонента стоит отдельно, лучше обойтись без артикля. Однако, если оно сочетается с нарицательным существительным, например, протоколом TON Connect, артикль необходим, поскольку он относится к протоколу сущности.

Что касается других словосочетаний, таких как «TON + существительное» (например, «мир TON», «сообщество TON» и т. д.), мы не ограничиваем использование артикля, поскольку мы, естественно, ожидаем увидеть артикль в сочетании с существительным.

Общие советы​

  • Не копируйте и не вставляйте ранее существовавший контент. Плагиат является серьезной проблемой и недопустим. Если в основу руководства положен какой-либо существующий контент, ознакомьтесь с ним и дайте ссылку на него. При размещении ссылок на другие учебные пособия / ресурсы, по возможности, используйте ресурсы TON Docs.
  • Включайте любые видео-руководства или видеоконтент в PR, загружая его на Google Диск.
  • Пополнение аккаунта с кранов должно быть четко объяснено, включая то, какой аккаунт пополняется, откуда и почему. Не думайте, что учащиеся могут выполнить эту задачу самостоятельно!
  • Отображайте примеры выходных данных в виде фрагментов терминала или снимков экрана, чтобы помочь учащимся понять, чего ожидать. Обрезайте длинные выходные данные.
  • Используйте подход, основанный на ошибках, когда вы специально сталкиваетесь с ошибками, чтобы научить учащихся, как их отлаживать. Например, если вам нужно пополнить счет, чтобы иметь возможность развернуть контракт, сначала попробуйте развернуть без пополнения, посмотрите на возвращаемую ошибку, затем исправьте ошибку (пополнив счет) и повторите попытку.
  • Добавьте потенциальные ошибки и способы устранения неполадок. Конечно, руководство не должно перечислять все возможные ошибки, но оно должно попытаться выявить важные или наиболее распространенные из них.
  • Используйте React или Vue для клиентской части.
  • Перед тем, как сделать PR, сначала запустите код самостоятельно, чтобы избежать очевидных ошибок и убедиться, что он работает так, как ожидается.
  • Избегайте включения внешних/перекрестных ссылок на разные источники между руководствами. Если ваше руководство длинное, мы можем обсудить, как превратить его в более длинный курс или Pathway.
  • Предоставьте изображения или скриншоты, чтобы проиллюстрировать сложные процессы, где это необходимо.
  • Загрузите свои изображения в каталог static репозитория learn-tutorials — НЕ используйте прямые ссылки на внешние сайты, так как это может привести к повреждению изображений.
  • Ссылки на изображения должны** быть в формате markdown, и вы должны ТОЛЬКО использовать необработанный URL-адрес GitHub статического каталога в репозитории: ![name of your image](https://raw.githubusercontent.com/ton-community/ton-docs/main/static/img/tutorials/<your image filename>.png?raw=true)
    • Не забудьте добавить ?raw=true в конец URL-адреса.

Как структурировать ваше учебное пособие​

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

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

  • Заголовок должен быть прямым и понятным, обобщающим цель руководства. Не добавляйте заголовок урока в качестве заголовка внутри документа; вместо этого используйте имя файла документа markdown.
    • Например: если ваше руководство называется "Пошаговое руководство по написанию вашего первого смарт-контракта на FunC", имя файла должно быть: step-by-step-guide-for-writing-your-first-smart-contract-in-func.md
  • Включите раздел Введение, объясняющий, почему это руководство важно каков его контекст. Не думайте, что это очевидно.
  • Включите раздел Предварительные требования, в котором объясняются требуемые предварительные знания или существующие учебные пособия, которые необходимо выполнить в первую очередь, любые необходимые токены и т. д.
  • Включите раздел Требования, в котором объясняются любые технологии, которые необходимо установить перед началом обучения и которые в руководстве не рассматриваются, например, расширение кошелька TON, Node.js и т.д. Не указывайте пакеты, которые будут установлены во время обучения.
  • Используйте подзаголовки (H2: ##), чтобы разбить ваши объяснения в тексте руководства. Помните о содержании при использовании подзаголовков и старайтесь, чтобы они были по существу.
    • Если содержимое под подзаголовком короткое (например, только один абзац и блок кода), рассмотрите возможность использования жирного текста вместо подзаголовка.
  • Включите раздел Заключение, который суммирует то, что было изучено, закрепляет ключевые моменты, а также поздравляет учащегося с завершением руководства.
  • (Необязательно) Включите раздел Что дальше, указывающий на хорошие последующие руководства или другие ресурсы (проекты, статьи и т. д.).
  • (Необязательно) Включите раздел Об Авторе в конце. Ваша биография должна включать ссылку на ваш профиль GitHub (где будет указано ваше имя, веб-сайт и т. д.) и ссылку на ваш профиль Telegram (чтобы пользователи могли связаться с вами/отметить вас для получения помощи и вопросов).
  • Раздел Ссылки должен присутствовать, если при написании этого руководства вы использовали какую-либо помощь из других документов, репозиториев GitHub или других руководств. Указывайте источники, добавляя их имя и ссылку на документ, когда это возможно (если это не цифровой документ, включите ISBN или другие средства ссылки).

Руководство по стилю​

  • Тон письма - Учебники пишутся участниками сообщества для своих коллег.

    • Учитывая это, мы рекомендуем создать тон включения и взаимодействия на протяжении всего учебника. Используйте такие слова, как «мы», «нас», «наш».
      • Например: «Мы успешно развернули наш контракт.»
    • При предоставлении прямых инструкций не стесняйтесь использовать «вы», «ваш» и т. д.
      • Например: "Ваш файл должен выглядеть так:".

  • Правильно используйте Markdown на протяжении всего учебника. Ознакомьтесь с руководством по Markdown на GitHub, а также с примером структуры руководства.

  • Не используйте предварительно отформатированный текст для выделения, например:

    • ❌ "TON counter smart contract с именем counter.fc" неверно.
    • ✅ "TON counter smart contract с именем counter.fc" верно.

  • Не используйте форматирование markdown в заголовке раздела, например:

    • ❌ # Введение неверно.
    • ✅ # Введение верно.

  • Объясните свой код! Не просите учащихся просто слепо копировать и вставлять.

    • Имена функций, переменные и константы должны быть одинаковыми во всем документе.

    • Используйте комментарий в начале блока кода, чтобы показать путь и имя файла, где находится код. Например:

      // test-application/src/filename.jsx

      import { useEffect, useState } from 'react';

      ...

  • Выберите соответствующий язык для подсветки синтаксиса блока кода!

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

  • Не используйте синтаксис блока кода для предварительно отформатированного текста, например:

    • ❌ `filename.jsx` неправильно.
    • ✅ `filename.jsx` правильно.

  • Ваши блоки кода должны быть хорошо прокомментированы. Комментарии должны быть короткими (обычно две или три строки за раз) и эффективными. Если вам нужно больше места для объяснения фрагмента кода, сделайте это за пределами блока кода.

  • Не забудьте оставить пустую строку перед всеми блоками кода и после них. Например:

  
// test-application/src/filename.jsx  
  
import { useEffect, useState } from 'react';
  • Используйте linter и prettifier перед вставкой кода в блоки кода. Мы рекомендуем eslint для JavaScript/React. Используйте prettier для форматирования кода.
  • Избегайте чрезмерного использования маркеров, нумерованных списков или сложного форматирования текста. Использование жирного или курсива выделения допускается, но должно быть сведено к минимуму.

Настройка приложения

  • Проекты Web3 обычно включают несколько существующих библиотек кода. Обязательно учитывайте это при написании своего руководства. По возможности предоставьте репозиторий GitHub в качестве отправной точки, чтобы облегчить учащимся начало работы.
  • Если вы не используете репозиторий GitHub для хранения кода, используемого в вашем руководстве, не забудьте объяснить читателям, как создать папку для организации кода. Например: mkdir example && cd example
  • Если вы используете npm init для инициализации каталога проекта, объясните подсказки или используйте флаг -y.
  • Если вы используете npm install, используйте флаг -save.