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