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

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

В этой статье

Сведения о документации по GitHub

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

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

  •         [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)

  •         [AUTOTITLE](/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)

  •         [AUTOTITLE](/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 используйте следующие типы контента:

  •         [Концептуальное содержимое](/contributing/style-guide-and-content-model/conceptual-content-type)

  •         [Ссылка на содержимое](/contributing/style-guide-and-content-model/referential-content-type)

  •         [Процедурное содержимое](/contributing/style-guide-and-content-model/procedural-content-type)

  •         [Устранение неполадок содержимого](/contributing/style-guide-and-content-model/troubleshooting-content-type)

  •         [Краткое руководство](/contributing/style-guide-and-content-model/quickstart-content-type)

  •         [Руководство](/contributing/style-guide-and-content-model/tutorial-content-type)

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

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

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

  •         **Укажите начальный контекст**. Определите раздел и укажите его релевантность для читателя.

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

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

  •         **Рекомендуется использовать ссылки на страницы** для более длинного содержимого. Это позволяет читателям переходить к областям интереса и пропускать содержимое, которое не имеет значения для них.

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

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

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

  •         **Используйте активный голос.**

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

Дополнительные сведения см. в разделе "Голос и тон" в [AUTOTITLE и Руководство по стилю](/contributing/writing-for-github-docs/writing-content-to-be-translated).

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

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

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

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

  •         **Используйте выделение текста, например полужирный шрифт и гиперссылки** , чтобы привлечь внимание к наиболее важным пунктам. Используйте выделение текста с разреженным образом. Не выделите более 10 % общего текста в статье.

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

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

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/style-guide)

  •         [AUTOTITLE](/contributing/style-guide-and-content-model/about-the-content-model)

  •         [AUTOTITLE](/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