# Рекомендации по GitHub Docs

Следуйте этим рекомендациям, чтобы создать документацию, удобную и удобную для понимания.

## О GitHub документации

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

Перед тем как внести вклад, GitHub Docsпожалуйста, уделите время, чтобы ознакомиться с GitHubфилософией документации, основами и принципами дизайна контента:

* [О философии документации GitHub](/ru/enterprise-server@3.22/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)
* [Основные сведения о документации GitHub](/ru/enterprise-server@3.22/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)
* [Принципы проектирования содержимого](/ru/enterprise-server@3.22/contributing/writing-for-github-docs/content-design-principles)

## Лучшие практики написания GitHub документации

Независимо от того, создаёте ли вы новую статью или обновляете существующую, следует следовать этим правилам при написании для GitHub Docs:

* [Выравнивание содержимого с учетом потребностей пользователя](#align-content-to-user-needs)
* [Структура содержимого для удобства чтения](#structure-content-for-readability)
* [Запись для удобства чтения](#write-for-readability)
* [Формат для проверки](#format-for-scannability)

## Выравнивание содержимого с учетом потребностей пользователя

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

### Определение аудитории

* Кто будет читать это содержимое?
* Какое действие клиент пытается выполнить?

### Определение основной цели

* Что кто-то должен иметь возможность делать или понимать после прочтения этой статьи? Выберите одну или две задачи или понятия, которые будут обсуждаться содержимым.
* Если существуют дополнительные задачи, понятия или сведения, которые не являются важными, рассмотрите возможность их размещения ниже в статье, перемещении в другую статью или опущены полностью.

### Определение типа контента

Определите тип содержимого, который вы будете писать, на основе целевой аудитории и основной цели содержимого.
GitHub Docs Используйте следующие типы контента:

* [Понятия, тип содержания](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/concepts-content-type)
* [Тип справочного контента](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/reference-content-type)
* [Тип контента с инструкциями](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/how-to-content-type)
* [Устранение неполадок с типом контента](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/troubleshooting-content-type)
* [Тип контента быстрого запуска](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/quickstart-content-type)
* [Тип контента учебника](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/tutorial-content-type)

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

## Структура содержимого для удобства чтения

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

* **Укажите начальный контекст**. Определите раздел и укажите его релевантность для читателя.
* **Структурируйте содержимое в логическом порядке** по важности и релевантности. Поместите сведения в порядке приоритета и в том порядке, в который пользователи будут нуждаться.
* **Избегайте длинных предложений и абзацев**.
  * Введите понятия по одному.
  * Используйте одну идею на абзац.
  * Используйте одну идею для каждого предложения.
* **Подчеркнуть наиболее важную информацию**.
  * Начните каждое предложение или абзац с наиболее важными словами и выносами.
  * При объяснении концепции начните с вывода, а затем объясните его более подробно. (Иногда это называется "инвертированная пирамида".)
  * При объяснении сложной темы сначала представляйте читателям основные сведения и раскрывайте подробности далее в статье.
* **Используйте значимые** подзаголовок. Упорядочение связанных абзацев в разделы. Присвойте каждому разделу подзаголовок, который является уникальным и точно описывает содержимое.
* **Рекомендуется использовать ссылки на страницы** для более длинного содержимого. Это позволяет читателям переходить к областям интереса и пропускать содержимое, которое не имеет значения для них.

## Запись для удобства чтения

Упростить чтение и понимание текста пользователями.

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

Дополнительные сведения см. в разделе "Голос и тон" в \[AUTOTITLE и [Руководство по стилю](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide#voice-and-tone)]\(/contributing/writing-for-github-docs/writing-content-to-be-translated).

## Формат для проверки

Большинство читателей не потребляют статьи в целом. Вместо этого они сканируют\_\_ страницу, чтобы найти определенную информацию, или *пропустить* страницу, чтобы получить общее представление о понятиях.

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

После четко определенной цели и структуры статьи можно применить следующие методы форматирования для оптимизации содержимого для сканирования и очистки. Эти методы также могут помочь сделать контент более понятным для всех читателей.

* **Используйте выделение текста, например полужирный шрифт и гиперссылки** , чтобы привлечь внимание к наиболее важным пунктам. Используйте выделение текста с разреженным образом. Не выделите более 10 % общего текста в статье.
* **Используйте элементы** форматирования для разделения содержимого и создания пространства на странице. Например:
  * Маркированные списки (с необязательными подзаголовоками запуска)
  * Нумерованные списки
  * [Оповещения](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide#alerts)
  * Таблицы
  * Визуальные элементы
  * Блоки кода и заметки кода

## Дополнительные материалы

* [Руководство по стилю](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/style-guide)
* [О con режим палатки l](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/about-the-content-model)
* [Содержание статьи на GitHub Docs](/ru/enterprise-server@3.22/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)
* [Рекомендации](https://readabilityguidelines.co.uk/) по удобочитаемости, дизайн содержимого в Лондоне
* [Перезапись цифрового контента для Brevity](https://www.nngroup.com/articles/rewriting-content-brevity/), Nielsen Норман Group