{"meta":{"title":"Рекомендации по GitHub Docs","intro":"Следуйте этим рекомендациям, чтобы создать документацию, удобную и удобную для понимания.","product":"Участие в документации GitHub","breadcrumbs":[{"href":"/ru/contributing","title":"Участие в документации GitHub"},{"href":"/ru/contributing/writing-for-github-docs","title":"Написание для GitHub Docs"},{"href":"/ru/contributing/writing-for-github-docs/best-practices-for-github-docs","title":"Рекомендации по GitHub Docs"}],"documentType":"article"},"body":"# Рекомендации по GitHub Docs\n\nСледуйте этим рекомендациям, чтобы создать документацию, удобную и удобную для понимания.\n\n## О GitHub документации\n\nВ GitHub, мы стремимся создавать документацию, которая будет точной, ценной, инклюзивной, доступной и простой в использовании.\n\nПеред тем как внести вклад, GitHub Docsпожалуйста, уделите время, чтобы ознакомиться с GitHubфилософией документации, основами и принципами дизайна контента:\n\n* [О философии документации GitHub](/ru/contributing/writing-for-github-docs/about-githubs-documentation-philosophy)\n* [Основные сведения о документации GitHub](/ru/contributing/writing-for-github-docs/about-githubs-documentation-fundamentals)\n* [Принципы проектирования содержимого](/ru/contributing/writing-for-github-docs/content-design-principles)\n\n## Лучшие практики написания GitHub документации\n\nНезависимо от того, создаёте ли вы новую статью или обновляете существующую, следует следовать этим правилам при написании для GitHub Docs:\n\n* [Выравнивание содержимого с учетом потребностей пользователя](#align-content-to-user-needs)\n* [Структура содержимого для удобства чтения](#structure-content-for-readability)\n* [Запись для удобства чтения](#write-for-readability)\n* [Формат для проверки](#format-for-scannability)\n\n## Выравнивание содержимого с учетом потребностей пользователя\n\nПрежде чем начать, важно понять, кто вы пишете, какие их цели являются, основные задачи или понятия, которые будет решать статья, и какой тип содержимого следует писать.\n\n### Определение аудитории\n\n* Кто будет читать это содержимое?\n* Какое действие клиент пытается выполнить?\n\n### Определение основной цели\n\n* Что кто-то должен иметь возможность делать или понимать после прочтения этой статьи? Выберите одну или две задачи или понятия, которые будут обсуждаться содержимым.\n* Если существуют дополнительные задачи, понятия или сведения, которые не являются важными, рассмотрите возможность их размещения ниже в статье, перемещении в другую статью или опущены полностью.\n\n### Определение типа контента\n\nОпределите тип содержимого, который вы будете писать, на основе целевой аудитории и основной цели содержимого.\nGitHub Docs Используйте следующие типы контента:\n\n* [Понятия, тип содержания](/ru/contributing/style-guide-and-content-model/concepts-content-type)\n* [Тип справочного контента](/ru/contributing/style-guide-and-content-model/reference-content-type)\n* [Тип контента с инструкциями](/ru/contributing/style-guide-and-content-model/how-to-content-type)\n* [Устранение неполадок с типом контента](/ru/contributing/style-guide-and-content-model/troubleshooting-content-type)\n* [Тип контента быстрого запуска](/ru/contributing/style-guide-and-content-model/quickstart-content-type)\n* [Тип контента учебника](/ru/contributing/style-guide-and-content-model/tutorial-content-type)\n\nНапример, используйте концептуальный тип контента, чтобы помочь читателям понять основы функции или раздела и как они могут помочь им достичь своих целей. Используйте процедурный тип контента, чтобы помочь людям выполнить определенную задачу с начала до конца.\n\n## Структура содержимого для удобства чтения\n\nЧтобы структурировать содержимое, используйте следующие рекомендации. При добавлении содержимого в существующую статью следуйте существующей структуре по возможности.\n\n* **Укажите начальный контекст**. Определите раздел и укажите его релевантность для читателя.\n* **Структурируйте содержимое в логическом порядке** по важности и релевантности. Поместите сведения в порядке приоритета и в том порядке, в который пользователи будут нуждаться.\n* **Избегайте длинных предложений и абзацев**.\n  * Введите понятия по одному.\n  * Используйте одну идею на абзац.\n  * Используйте одну идею для каждого предложения.\n* **Подчеркнуть наиболее важную информацию**.\n  * Начните каждое предложение или абзац с наиболее важными словами и выносами.\n  * При объяснении концепции начните с вывода, а затем объясните его более подробно. (Иногда это называется \"инвертированная пирамида\".)\n  * При объяснении сложной темы сначала представляйте читателям основные сведения и раскрывайте подробности далее в статье.\n* **Используйте значимые** подзаголовок. Упорядочение связанных абзацев в разделы. Присвойте каждому разделу подзаголовок, который является уникальным и точно описывает содержимое.\n* **Рекомендуется использовать ссылки на страницы** для более длинного содержимого. Это позволяет читателям переходить к областям интереса и пропускать содержимое, которое не имеет значения для них.\n\n## Запись для удобства чтения\n\nУпростить чтение и понимание текста пользователями.\n\n* **Используйте обычный язык.** Используйте распространенные, повседневные слова и избегайте жаргона, когда это возможно. Термины, хорошо известные разработчикам, подходят, но не стоит предполагать, что читатель знает детали того, как GitHub это работает.\n* **Используйте активный голос.**\n* **Будьте краткими.**\n  * Напишите предложения, которые являются простыми и краткими.\n  * Избегайте сложных предложений, содержащих несколько понятий.\n  * Синтаксический анализ ненужных сведений.\n\nДополнительные сведения см. в разделе \"Голос и тон\" в \\[AUTOTITLE и [Руководство по стилю](/ru/contributing/style-guide-and-content-model/style-guide#voice-and-tone)]\\(/contributing/writing-for-github-docs/writing-content-to-be-translated).\n\n## Формат для проверки\n\nБольшинство читателей не потребляют статьи в целом. Вместо этого они сканируют\\_\\_ страницу, чтобы найти определенную информацию, или *пропустить* страницу, чтобы получить общее представление о понятиях.\n\nПри сканировании или сканировании содержимого средства чтения пропускают большие фрагменты текста. Они ищут элементы, связанные с их задачей или выделяющиеся на странице, такие как заголовки, оповещения, списки, таблицы, блоки кода, визуальные элементы и первые несколько слов в каждом разделе.\n\nПосле четко определенной цели и структуры статьи можно применить следующие методы форматирования для оптимизации содержимого для сканирования и очистки. Эти методы также могут помочь сделать контент более понятным для всех читателей.\n\n* **Используйте выделение текста, например полужирный шрифт и гиперссылки** , чтобы привлечь внимание к наиболее важным пунктам. Используйте выделение текста с разреженным образом. Не выделите более 10 % общего текста в статье.\n* **Используйте элементы** форматирования для разделения содержимого и создания пространства на странице. Например:\n  * Маркированные списки (с необязательными подзаголовоками запуска)\n  * Нумерованные списки\n  * [Оповещения](/ru/contributing/style-guide-and-content-model/style-guide#alerts)\n  * Таблицы\n  * Визуальные элементы\n  * Блоки кода и заметки кода\n\n## Дополнительные материалы\n\n* [Руководство по стилю](/ru/contributing/style-guide-and-content-model/style-guide)\n* [О con режим палатки l](/ru/contributing/style-guide-and-content-model/about-the-content-model)\n* [Содержание статьи на GitHub Docs](/ru/contributing/style-guide-and-content-model/contents-of-a-github-docs-article)\n* [Рекомендации](https://readabilityguidelines.co.uk/) по удобочитаемости, дизайн содержимого в Лондоне\n* [Перезапись цифрового контента для Brevity](https://www.nngroup.com/articles/rewriting-content-brevity/), Nielsen Норман Group"}