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