Практические руководства¶
Практические руководства — это указания, которые помогают читателю решить проблему или достичь результата. Практические руководства ориентированы на достижение целей.
Практическое руководство помогает пользователю выполнить задачу правильно и безопасно; оно направляет его действия.
Оно посвящено работе — поиску пути через реальное проблемное поле.
Примеры: как откалибровать антенную решётку радара; как использовать фикстуры в pytest; как настроить задержки между попытками переподключения. А вот как создать веб-приложение — не практическое руководство: этот материал не посвящён конкретной цели или проблеме, а охватывает огромную, почти безграничную область навыков.
Практические руководства важны не только потому, что помогают пользователям решать задачи. Их перечень в документации показывает, что продукт на самом деле умеет делать. Обширный набор практических руководств убедительно говорит о возможностях продукта.
Хорошо написанные практические руководства, отвечающие на нужные вопросы, скорее всего, станут самыми читаемыми разделами документации.
Практические руководства должны быть посвящены проблемам¶
Практические руководства нужно писать с точки зрения пользователя, а не системы. Каждое из них представляет дело, которое человеку нужно выполнить, иными словами — определяется потребностями пользователя. Практическое руководство должно отвечать реальной цели человека и показывать, как с помощью доступных инструментов получить нужный результат.
Этому противоположен распространённый подход, при котором практические руководства определяются операциями, доступными в инструменте или системе. Такой подход почти не приносит пользы, потому что не отвечает ни одной потребности пользователя. В центре внимания оказывается инструмент и его механика, а не задача человека.
В основе этого различия лежит осмысленность. Смысл возникает из цели и потребности. У функций машины самих по себе нет ни цели, ни потребности — это лишь цепочка причин и следствий, входов и выходов.
Рассмотрим примеры:
«Чтобы перекрыть воду, поверните кран по часовой стрелке».
«Чтобы развернуть нужную конфигурацию базы данных, выберите соответствующие параметры и нажмите Развернуть».
Примеры выше выглядят как полезные указания, но на деле ими не являются.
По большей части это бесполезные сведения, которые должен знать любой человек с базовой компетентностью в данной области. Стандартные интерфейсы в сочетании с общепринятыми знаниями и без того ясно показывают, к чему приведёт большинство действий.
Во-вторых, эти примеры оторваны от цели. Пользователю могут понадобиться, например, такие сведения:
сколько воды и какой напор нужны для конкретной цели
какие параметры конфигурации базы данных соответствуют конкретным реальным потребностям
В практических руководствах инструменты играют лишь вспомогательную роль: это средства достижения цели пользователя. Иногда конкретная цель тесно связана с одним инструментом или частью системы — тогда руководство действительно сосредоточено на них. Но не реже оно охватывает разные инструменты и части системы, связывая их в последовательность действий, которую определяет реальная задача человека. В обоих случаях именно эта задача задаёт содержание практического руководства.
Чем практические руководства не являются¶
Практические руководства принципиально отличаются от учебных руководств. Их часто путают, хотя они отвечают на совершенно разные потребности пользователя. Смешение этих типов лежит в основе многих проблем документации. Подробнее об этом различии см. в разделе Различие между учебным и практическим руководством.
Есть и другое заблуждение: практические руководства нередко считают всего лишь пошаговыми процедурами. Однако решение проблемы или выполнение задачи не всегда сводится к процедуре. У реальных проблем не всегда бывают линейные решения. Последовательности действий могут разветвляться и пересекаться, иметь несколько точек входа и выхода. Нередко пользователю приходится опираться на собственное суждение, применяя предложенные рекомендации.
Ключевые принципы¶
Практическое руководство посвящено работе — задаче или проблеме с конкретной практической целью. Не теряйте эту цель из виду.
Всё лишнее отвлекает и вас, и пользователя и ослабляет пользу руководства. Чаще всего возникает соблазн что-либо объяснить или ради полноты добавить справочные сведения. Ни то ни другое не помогает направлять действия пользователя — наоборот, мешает им. Если эти материалы важны, дайте на них ссылки.
Практическое руководство помогает в работе уже компетентному пользователю. Можно исходить из того, что он знает, чего хочет добиться, и способен правильно выполнить инструкции.
Учитывайте сложность реального мира¶
Практическое руководство должно допускать адаптацию к реальным сценариям. Материал, полезный лишь для точно такого узкого случая, который вы описали, редко представляет большую ценность. Рассмотреть все варианты невозможно, поэтому оставляйте руководство достаточно гибким, чтобы пользователь мог приспособить рекомендации к своим потребностям.
Опустите ненужное¶
В практическом руководстве практическая применимость важнее полноты. Учебное руководство должно полностью провести читателя от начала до конца, а практическое — не обязано. Оно должно начинаться и заканчиваться в разумных, осмысленных точках, а читатель сам встроит его в свою работу.
Давайте последовательность указаний¶
Практическое руководство предлагает решение реальной проблемы или задачи в виде конкретных действий. Это своего рода договор: если вы столкнулись с такой ситуацией, то сможете справиться с ней, пройдя предложенные шаги. Каждый шаг представляет собой действие.
Под «действиями» здесь понимаются не только физические действия, но также размышления и суждения: чтобы решить проблему, её нужно обдумать. Практическое руководство должно направлять и мысли, и действия пользователя.
Опишите логическую последовательность¶
В основе практического руководства лежит последовательность. Она подразумевает логический порядок во времени: выбранный порядок должен иметь смысл.
Во многих случаях порядок диктуется самими условиями: например, второй шаг можно выполнить только после первого. Тогда последовательность указаний очевидна.
Иногда выбор тоньше. Две операции можно выполнить в любом порядке, но одна из них, например, может подготовить рабочую среду или даже ход мыслей пользователя так, что вторую будет выполнить проще. Это веская причина поставить её первой.
Добивайтесь плавного хода¶
Всегда соотносите последовательность с привычным ходом действий и мыслей пользователя, чтобы руководство обрело плавность и позволяло двигаться вперёд без рывков.
Плавный ход показывает, что вы хорошо понимаете пользователя. Чтобы выстроить осмысленный порядок, нужно учитывать, как люди думают и действуют и что нужно человеку, который следует указаниям.
Иногда всё очевидно: процесс, в котором пользователь постоянно переключается между контекстами и инструментами, явно неудобен и неэффективен. Но стоит смотреть глубже. О чём вы предлагаете пользователю думать и как его мысль будет переходить от одного предмета к другому? Как долго ему придётся удерживать мысль незавершённой, прежде чем он сможет завершить её действием? Если нужно возвращаться к уже пройденному, действительно ли без этого нельзя обойтись?
Практическое руководство задаёт не только логический порядок, но и развитие действий во времени. И у самого действия, и у ведущего к нему руководства есть темп и ритм. Неудачный темп или сбитый ритм нарушают плавность работы.
В лучшем случае практическая документация обеспечивает пользователю плавный ход работы. Особенно хорошо это ощущается, когда руководство словно предугадывает следующий шаг. Это аналог такой ситуации в документации: помощник уже держит наготове инструмент, за которым вы только собирались потянуться.
Продумывайте названия¶
Выбирайте заголовки, которые точно сообщают, что показывает практическое руководство.
хорошо: Как интегрировать мониторинг производительности приложений
плохо: Интеграция мониторинга производительности приложений (возможно, документ рассказывает, как решить, нужна ли интеграция, а не как её выполнить)
очень плохо: Мониторинг производительности приложений (может быть, материал о том, как его внедрить, а может — о том, стоит ли это делать, или вообще объясняет, что это такое)
Хорошие заголовки ценят не только люди, но и поисковые системы.
Язык практических руководств¶
- В этом руководстве показано, как…
Ясно опишите проблему или задачу и покажите в руководстве, как её решить.
- Если вам нужно x, сделайте y. Чтобы получить w, сделайте z.
Формулируйте указания как условие и действие.
- Полный список параметров приведён в справочнике по x.
Не перегружайте практическое руководство всеми возможными действиями пользователя, связанными с x.
На примере еды и кулинарии¶
Рассмотрим рецепт — прекрасный образец практического руководства. В рецепте ясно определён результат и дан ответ на конкретный вопрос: Как приготовить…? или Что приготовить из…?
Рецепт не обязан учить вас готовить. Даже профессиональный повар, много раз готовивший то же блюдо, может сверяться с рецептом — пусть даже он сам его создал, — чтобы не ошибиться.
Даже следование рецепту требует хотя бы базовых навыков. Нельзя ожидать, что человек, который никогда не готовил, успешно справится с рецептом. Поэтому рецепт не заменяет урок кулинарии.
Тот, кто рассчитывал получить рецепт, а вместо него получил урок кулинарии, будет разочарован и раздражён. Читать о контексте или истории блюда тоже интересно, но меньше всего хочется сталкиваться с этим посреди готовки. Хороший рецепт следует устоявшемуся формату: исключает обучение и обсуждение и сосредоточен только на том, как приготовить выбранное блюдо.