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

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

warning

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

Введение​

Это руководство призвано помочь вам определить вашу аудиторию, которая повлияет на стиль и размещение вашего контента.

Аудитория​

Документация TON (docs.ton.org) — это ресурс, разработанный для трех основных аудиторий.

Концепции для отдельных лиц: Независимо от того, являются ли читатели новыми пользователями приложений, инвесторами или энтузиастами блокчейна, они найдут ответы на свои вопросы о надежности TON, возможностях кошелька, вовлеченности сообщества и технической дорожной карте. Концепции упрощают сложные абстракции, чтобы читатели могли уверенно вникать в суть.

Рекомендации для внешних разработчиков: Читатели могут узнать, как запускать узлы, быстро создавать примеры проектов и интегрировать свои проекты с TON — все это представлено в виде простых пошаговых инструкций. Для разработчиков, которые практически не имеют опыта работы с блокчейном, этот материал представляет собой практическое введение в технологический стек TON.

Документация для разработчиков TON: Раздел документации посвящен улучшению опыта разработчиков с помощью глубокой и подробной документации. Здесь технические эксперты могут ознакомиться с лучшими практиками и технической информацией для разработки смарт-контрактов промышленного уровня и приложений для глобального рынка. Это также руководство для тех, кто планирует улучшить программное обеспечение для блокчейна и обновить протоколы TON.

Концепции для отдельных лиц​

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

Примерные пути развития:

  • “Я хочу проверить надежность TON и, ответив на несколько основных вопросов, попробовать его использовать.”
  • “Я знаю, что мне нужен кошелек TON, и я хочу узнать, как он работает.”
  • “Я хочу получить представление об активности сообщества TON, чтобы решить, достаточно ли оно активно, чтобы я мог обратиться за помощью в случае необходимости.”
  • “Я в восторге от TON и хочу принять участие, но не знаю, что делать дальше.”
  • "Я хочу узнать о технической дорожной карте TON."

Рекомендации для внешних разработчиков​

Примерные пути развития для внешних разработчиков:

  • “Я разработчик, но у меня нет опыта в криптографии, и я хочу разобраться в технологическом стеке TON.”
  • “Я хочу научиться управлять узлом TON/”
  • “Я хочу быстро запустить пример проекта TON, чтобы понять, насколько сложно или легко создать настоящий проект на TON.”
  • "Я начал работать над интеграцией своего проекта в TON и хочу выяснить, как это сделать лучше всего.”

Документация для разработчиков TON​

Примерные пути развития для разработчиков TON:

  • "Я хочу разработать промышленные смарт-контракты для экосистемы TON в соответствии с передовой практикой и спецификациями."
  • "Я хочу участвовать в разработке программного обеспечения блокчейна TON."
  • "Я хочу обновить протоколы TON, чтобы улучшить пользовательский опыт."
  • "Я хочу обновить спецификацию TON, чтобы повысить удобство работы для разработчиков."

Рекомендации по стилю​

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

Концепции и рекомендации​

Это общие проблемы контента для читателей концепций и руководств.

Распространенные проблемы с контентом:​

  • Перегруженность специфическими техническими терминами
  • Несогласованность содержания на разных страницах
  • Статьи трудно усваиваются из-за того, что
  • Содержание слишком абстрактно и оторвано от реальности
  • Слишком много текста на странице и абзаце
  • Использование сложных предложений
  • Слишком большое количество ссылок может привести к перегрузке читателей, в результате чего они покинут веб-сайт

Чтобы контент соответствовал своей аудитории, соблюдайте следующие правила.

Концепции и рекомендации, которые являются наилучшей практикой​

  • Сосредоточьтесь на преимуществах для пользователя, а не на объяснении технических деталей системы
  • Используйте активную речь и четкие, сжатые предложения, которые легко понять
  • Разбивайте длинные фрагменты текста на более мелкие разделы или абзацы
  • Рассмотрите возможность использования таблиц, маркеров или нумерованных списков вместо абзацев
  • Выделите жирным шрифтом ключевые фразы для удобства сканирования и беглого просмотра статьи
  • Ограничьте объем статьи до 2000 слов
  • Сократите количество гиперссылок примерно до 10 на 2000 слов.
  • Исходите из того, что люди только начали интересоваться технологией блокчейн
  • Пользователи хотят понять, как тема связана с ними и как они могут принять в ней участие, а не углубляться в теорию

Стиль документации​

Для читателей документации это список типичных проблем с содержанием.

Проблемы с документацией​

  • Несоответствия в документации
  • Разные, неясные и противоречивые формулировки и терминология
  • Длинные предложения, написанные страдательным залогом
  • Устаревшая информация
  • Предоставляется только код, без объяснений и документации

Сделайте документацию по содержанию привлекательной для аудитории, придерживаясь следующих правил.

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

  • Как можно скорее публикуйте обновленную документацию по изменениям.
  • Предоставляйте подробные и понятные объяснения всех компонентов системы и процессов.
  • Используйте диаграммы, примеры и выделенные ключевые моменты для поддержки текста.
  • Структурируйте контент таким образом, чтобы сочетать подробную информацию на странице со стратегическими перекрестными ссылками, обеспечивая простоту навигации, не перегружая при этом ни одну страницу.
  • Унифицируйте контент в соответствии с руководствами по вкладам.
  • Используйте активную речь для составления четких, прямых предложений для сложных абстракций.
  • Разбивайте длинные предложения на более короткие и простые, чтобы улучшить читаемость.

Идеи для контента​

Весь раздел​

  • Предоставьте наглядные пособия, чтобы лучше объяснить тему
  • Обновите стиль и проведите корректуру

Концепции​

  • Используйте примеры или реальные сценарии применения технологии, чтобы проиллюстрировать сложные концепции или идеи
  • Объясните, как идея может положительно повлиять на людей сейчас или в будущем

Рекомендации​

  • Добавьте пошаговое руководство по выполнению действий
  • Включите соответствующую статистику или графики, чтобы подкрепить аргументы
  • Добавьте призывы к действию

Документация​

  • Обновите или улучшите существующую документацию.
  • Добавьте полную новую документацию о сущности TON: узел, оракул, смарт-контракт или TVM в целом.

Объективность​

Документация TON призвана служить надежным, нейтральным источником информации, информирующим читателей об экосистеме TON, ее технологиях и развитии. Ниже приведены примеры контента, которые не будут приняты к рассмотрению:

Грандиозные, непроверяемые утверждения о TON или смежных технологиях. - Пример: "Вы должны купить TON для раздачи подарков..."

Враждебные или конфронтационные высказывания в адрес какой-либо организации или человека - Пример: _ "Компания X плоха, потому что она централизована!"_

Политизированная риторика - Пример: "Эта политическая партия лучше подходит для децентрализации, потому что..."

warning

Любой предлагаемый контент, который не соответствует целям платформы, будет отклонен без дополнительных объяснений. Спам и неподобающее поведение в комментариях приведут к блокировке.

Согласованность​

Подробно ознакомьтесь со следующими руководствами и поддерживайте соответствие контента.

  • Стандартизация контента - Узнайте, как правильно организовывать контент, добавлять изображение, атрибут и т. д.
  • Типографика - Изучите лучшие методы работы с обычным текстом и заголовками.

См. также​