Учебники помогают людям узнать о продуктах и решать реальные проблемы, управляя им через весь рабочий процесс для выполнения задачи. Учебники являются более разговорными в тоне, чем другое содержимое. Учебник чувствует себя как беседа разработчика и разработчика, оставаясь доступной для читателей с различными техническими знаниями. Продукты с руководствами уже должны иметь краткое руководство. Для рабочих процессов размера укуса используйте модель быстрого запуска.
Учебники предназначены для людей, которые хотят экспертных консультаций и подробного обсуждения рекомендаций, связанных с их проблемой. Учебники также помогают людям, которые реализовали аналогичные решения в прошлом с другими продуктами, используют GitHub. Руководства также могут помочь людям проверить, подходит ли решение для их потребностей.
Мы совместно ссылаемся на учебники и краткие руководства как "руководства" по всему сайту. На /guides целевых страницах мы включаем руководства, краткие руководства и некоторые процедурные статьи в список руководств для набора документов.
Создание учебника
Шаблон руководства см. в разделе "Шаблоны".
Содержимое учебников:
- Введение
- Уточняет аудиторию.
- Четко указывает необходимые условия и предварительные знания.
- Указывает, что кто-то будет выполнять или строить.
- Включает пример успешного проекта.
- Не включает ожидаемое количество времени, которое может занять кто-то для выполнения задачи. Это зависит от уровня опыта пользователя, выполняющего учебник.
- Процедурные разделы
- На основе аудитории руководства шаги могут быть менее явными и формальными, чем те, которые используются в процедурном содержимом. Вам не нужно использовать существующие многократно используемые средства для формирования этих шагов, если аудитория не требует этого уровня детализации.
- Используйте команду "Из профиля щелкните Параметры, а затем щелкните "Параметры разработчика".
- Избегайте. В правом верхнем углу любой страницы щелкните фото профиля, а затем щелкните Параметры. На левой боковой панели щелкните Developer settings (Параметры разработчика).
- Ссылки на другие статьи или ресурсы, а не реплика их, чтобы избежать прерывания потока информации в руководстве.
- Предоставьте визуальные подсказки. Используйте блоки кода и снимки экрана, чтобы убедить людей, что они выполняют правильные действия.
- Укажите реальные примеры.
- Например, не сообщайте пользователю "Ввести сообщение о фиксации" вместо этого присвойте им соответствующий пример фиксации сообщения, соответствующего предыдущим шагам.
- На основе аудитории руководства шаги могут быть менее явными и формальными, чем те, которые используются в процедурном содержимом. Вам не нужно использовать существующие многократно используемые средства для формирования этих шагов, если аудитория не требует этого уровня детализации.
- Устранение неполадок
- Подтвердите, что может пойти не так в задаче, и перечислите несколько распространенных проблем, которые читатели могут столкнуться с решениями.
- Заключение
- Просмотрите, что было сделано или построено. Вернитесь к проекту, указанному в вводном представлении, в качестве примера успешного проекта.
- Следующие шаги
- Включите 2-3 действия, которые можно предпринять после выполнения руководства. Связывание с другими связанными сведениями, например:
- Проекты на GitHub, иллюстрирующие представленные понятия
- Соответствующая информация о docs.github.com
- Релевантные данные GitHub Skills
- Соответствующие опубликованные переговоры, записи блога или публикации серии форумов сообщества Hubbers
- Включите 2-3 действия, которые можно предпринять после выполнения руководства. Связывание с другими связанными сведениями, например:
Руководство по заголовку учебников
- Следуйте инструкциям по заголовкам процедурных статей.
- Не используйте "учебник" или "руководство" в заголовке.
Примеры учебников
Руководства.
- Добавление меток к проблемам
- Установка сертификата Apple в средствах выполнения macOS для разработки в Xcode
Руководства по языку и платформе: