Краткие руководства позволяют людям быстро выполнять дискретную, ориентированную задачу, иллюстрируя рабочий процесс только важными шагами, примерно через пять минут или 600 слов. Краткие руководства можно использовать для быстрого настройки с помощью нового инструмента или быстрого выполнения другой задачи. Для более сложных задач используйте учебник.
Краткие руководства полезны, когда кто-то уже понимает функцию или продукт и готов попробовать ее.
Мы совместно ссылаемся на учебники и краткие руководства как "руководства" по всему сайту. На /guides целевых страницах мы включаем руководства, краткие руководства и некоторые процедурные статьи в список руководств для набора документов.
Как написать краткое руководство
Шаблон краткого руководства см. в разделе Шаблоны.
Содержимое кратких руководств:
- Введение:
- Подчеркивает, что это руководство быстро и в точке с помощью фраз, таких как:
- Быстрое добавление [FEATURE] в проект
- Основные сведения о начале работы с [PRODUCT]
- Сокращенное руководство для людей, знакомых с [FEATURE]
- Уточняет аудиторию
- Четкое состояние предварительных требований и предварительных знаний
- Указывает, что кто-то будет выполнять или строить
- Подчеркивает, что это руководство быстро и в точке с помощью фраз, таких как:
- Процедурные разделы
- На основе аудитории краткого руководства шаги могут быть менее явными и формальными, чем те, которые используются в процедурном содержимом. Вам не нужно использовать существующие многократно используемые средства для формирования этих шагов, если аудитория не требует этого уровня детализации.
- Связать с другими статьями или ресурсами, а не реплицировать их, чтобы избежать прерывания потока информации.
- Предоставьте визуальные подсказки. Используйте блоки кода и снимки экрана, чтобы убедить людей, что они выполняют правильные действия.
- Устранение неполадок (необязательно)
- Если для краткого руководства существует соответствующее содержимое по устранению неполадок, укажите ссылки на него.
- Следующие шаги
- Предоставьте краткий обзор того, что было сделано в кратком руководстве в качестве средства перехода к следующим шагам.
- Включите 2-3 действия, которые можно предпринять после выполнения краткого руководства. Всегда ссылаться на концептуальное содержимое компонента или продукта. Вы также можете связать с другими связанными сведениями о docs.github.com или GitHub Skills.
Рекомендации по заголовку для кратких руководств
- Когда руководство помогает кому-то приступить к работе с новым инструментом, предусловит заголовок с помощью краткого руководства, например "Краткое руководство по GitHub Actions" или "Краткое руководство. Процедурное название".
- Для других вариантов использования следуйте инструкциям по заголовку процедур и опустите слово "Краткое руководство".