Руководства

Руководство должно помочь начинающему достичь базовой компетенции с продуктом, такой, чтобы они могли продолжить пользоваться продуктом для своих собственных целей.

Руководство также должно показывать обучающимся, что они могут достигать успехов с продуктом, предлагая им делать что-то одновременно значимое и достижимое.

Другими словами, руководство — это урок, чтобы скорее "научиться как", чем "узнать что", ведь он служит усвоению навыка — практического, а не теоретического знания.

Завершив руководство, обучающийся получает начальные представления об остальной документации и о самом продукте.

Для продукта руководства превращают изучающих в пользователей. А неадекватное руководство может и помешать проекту в наборе новых пользователей.

Руководство как урок ​

Урок предполагает взаимодействие между учителем и учеником. В обучении такого рода научение происходит через то, что ученик делает.

Любые факты и объяснения, представляемые во время обучения практически на связаны с тем, чему ученик научится. Что имеет значение — так это то, что учитель дает ученику делать.

Для наших целей, урок — это опыт обучения. Если вы не предоставляете вашим обучающимся такого опыта, руководство не делает того, что должно делать.

Обязательства учителя ​

У учителя есть ответственность за то, что ученику предстоит узнать, что он будет для этого делать и за его успех в этом. Единственная обязанность ученика — это быть внимательным и следовать указаниям учителя настолько точно, насколько он может. На ученика не возлагается ответсвенность за заучивание, понимание или запоминание, единственное его обязательство в этом контракте — делать то, что ему указывают.

В то же время упражнения, через которые вы ведете ученика должны быть:

• значимы — ученик нуждается в чувстве достижения,
• успешны — ученик должен иметь возможность их выполнить,
• логичны — путь, который проходит ученик, должен быть осмысленным,
• наполнены пользой — ученик должен встретиться со всеми действиями, концепциями и инструментами, с которыми ему необходимо освоиться в дальнейшем.

Быть учителем не легко.

Проблема руководств ​

Как правило, руководства — самая слабая часть документации, самая неправильно понимаемая и трудная в разработке. У большинства программных продуктов как правило очень слабые руководства, если вообще есть.

В идеальном уроке, учитель присутствует, взаимодействует со студентами и отвечает на их запросы. Письменное руководство далеко не лучшая замена для этого.

Чистого времени для разработки и поддержки руководств требуется намного больше, чем для других частей документации. Достаточно сложно создать опыт обучения, который будет соответствовать всем перечисленным выше стандартам. Во многих контекстах сам продукт быстро развивается, что означает что вся работа должна быть сделана заново, чтобы убедиться что руководство по прежнему выполняет необходимые функции.

И, наконец, вы обнаружите, что никакая другая из вашей документации не подвержена пересмотру так, как руководства. Вам достаточно изменить справочник или инструкцию, если что-то меняется в продукте, а часто исправить нужно лишь небольшую их часть. В случае руководства вы можете прийти к выводу, что целый урок нужно полностью переписать, т.к. вы придумали лучший способ создать педагогический опыт для учащихся.

Вы легко обнаружите, что написание и поддержание руководств занимает столько же времени и энергии, как все три остальных части вместе взятые.

Еда и готовка ​

Возможно, у вас был опыт обучения детей приготовлению пищи. В таком случае, вы уже сталкивались с большинством их главных требований к руководству.

Как вы, возможно, поняли, если не знали раньше: главная вещь в этом опыте — не то, что вы учите ребенка готовить. Единственная вещь, которая важна, это то, что ребенок наслаждается самим опытом работы на кухне вместе с вами, набирается уверенности и хочет делать это снова.

Это должно быть результатом опыта обучения на кухне. А если это не так, то даже если ребенок и узнал что-то, путь обучения рискует на этом закончиться.

Учитель всегда чувствует некоторую естественную озабоченность тем, что ученик должен изучить. И есть соблазн надавить в этом слишком сильно, что одновременно не необходимо и контр-продуктивно.

Ребенок выучит, в свое время и в своем темпе, через действия, которые вы делаете вместе, а не через вещи, которые вы говорите или показываете.

Со временем это научит его главным вещам через повторение: как держать нож, что важно мыть руки перед обращением с едой, как использовать измерительные приборы, как засекать время. Это научит его каково это работать на кухне, где найти приборы.

С маленьким ребенком вы часто обнаруживате, что урок внезапно подошел к концу до того, как вы выполнили то, что собирались. Это нормально и ожидаемо, у детей очень маленьких объем внимания. Если ребенок смог достичь чего-то, хотя бы малого, и получил удовольстве от процесса, это заложит что-то в конструкцию его технической экспертизы, к которой можно вернуться в следующий раз и начать строить что-то уже поверх этого.

Готовка — это вопрос ремела. Это знание, но это практическое знание, не _ теоретическое_. Это одинаково для любого продукта: использование его — это навык, а когда мы изучаем новое умение или навык, мы всегда начинаем через обучение действием.

Написание хорошего руководства ​

Анти-педагогические соблазны

• абстракции и обобщения
• объяснения
• выбор
• информация

Не пытайтесь учить ​

Позвольте пользователю учиться. В начале мы учимся только деланием — именно так мы учимся говорить или ходить.

Дайте обучающемуся что-то делать, через что он может научиться. Только ваш ученик может учиться. К сожалению, как бы вы этого не хотели, вы не сможете учиться за вашего ученика. Вы не можете заставить их учиться. Все, что вы можете — это сделать так, чтобы они учились сами.

По мере того, как вы ведете ученика через предложенные вами шаги, давайте им использовать инструменты и выполнять операции, с которыми им необходимо освоиться, постепенно переходя от самых простых к более сложным.

Помогите пользователям начать ​

Ваша работа — помочь обучающимся начать, не превратить их в экспертов. Никогда не сущайтесь начать прямо с начала: пользователь может быстро проскочить все несущественное, но если они нуждаются в чем-то и этого нет, вы рискуете упустить из насовсем. Также вполне приемлемо если то, что вы предлагаете делать начинающим, делается не так, как это делал бы опытный человек, даже если это не "правильный" способ — руководство для начинающих — не тоже самое, что инструкции по лучшим практикам.

Смысл руководства — помочь обучающемуся благополучно отправиться в путь, а не доставить их в конечный пункт назначения.

Единственная причина не понижать планку — если вы решите, что не хотите нести ответственности за обучение новичков ниже определенного уровня или вы считаете, что определенный уровень навыков является разумным предварительным условием для использования продукта в целом.

Предоставьте полную картину перед тем, как начинать ​

Важно позволить обучающимся сформировать представление о том, чего они достигнут, с самого начала. Это не только помогает определить ожидания, но и дает им возможность увидеть себя, продвигающимися к конечной цели по мере работы. Удивляя их результатом в конце мы приуменьшаем, а не преувеличиваем ценность того, что они достигли. Очень приятно с размахом показывать впечатляющие выводы, но вам стоит оставить это для ваших фокусов и романов.

Предоставление картины, в котором нуждается обучающийся, в руководстве может быть выражено в простом информировании их в самом начале: В этом руководстве вы построите простой сайт с использованием Django и опубликуете его с использованием Docker. В процессе вы будете использовать сервис облачного хранилища для обработки медиа-файлов и будете настраивать конфигурацию вашего приложения для работы.

Убедитесь, что руководство работает надежно ​

Одна из ваших обязянностей в качестве наставника — внушать новичкам уверенность. Уверенность можеть быть построена только слой за слоем, но ее легко растерять. Она помогает поддерживать дружественный тон, а также последовательное использование языка и логичное продвижение через материал. Однако, единственное наиболее важное требование — то, что вы предлагаете новичку делать, должно работать. Ученикам нужно видеть, что когда они следуют вашим указаниям, они получают обещанные результаты.

Создание надежного опыта — тяжелая работа, но это то, к чему вы должны стремиться в создании руководства.

Убедитесь, что пользователь видит результаты незамедлительно ​

Ваш ученик, возможно, делает новые и странные вещи, которые еще не понимает. Не заставляйте его делать слишком много до того, как он увидит результат своих действий. Насколько возможно, последствия каждого действия должны быть для него ясны как можно раньше. Связь причины и следствия должны быть очевидны. В конце концов, каждый результат должен быть чем-то, что пользователь сможет воспринять как значимый.

Каждый шаг, которому следует обучающийся должен давать понятный результат, какой бы маленький он ни был.

Сделайте ваше руководство воспроизводимым ​

Если только вам не очень повезет, пользователи вашего руководства будут обладать разным уровнем умений и понимания. Они могу также использовать разные инструменты и операционные системы и вы не можете рассчитывать на то, что у них будут одинаковые ресурсы и окружение.

Это делает достижение воспроизводимой надежность крайне сложной задачей, однако ваше руководство должно работать для всех пользователей, каждый раз.

У вас нет другой альтернативы, кроме как тестировать ваши руководства регулярно, чтобы убедиться, что они по прежнему работают как ожидалось.

Описывайте конкретные шаги, не абстрактные концепции ​

Руководства состоят из конкретных шагов, не абстрактного обсуждения. Будьте точны и конкретны, говорите о действиях и их результатах.

Сопротивляйтесь соблазнам ввести абстракции. Любое обучение продвигается от частного и конкретного к общему и абстрактному. Позже, когда начинающий встретился с несколькими конкретными примерами, он становится готов увидеть в них закономерности и искать абстрактные описания того, что происходит. Требовать от обучающегося осмыслять уровни абстракции до того, как он получил шанс освоить конкретные вещи, запутывает его и возлагает на его плечи ненужное бремя.

Сложно сопротивляться этим соблазнам, ведь когда мы уже освоили что-то, мы опираемся на силу абстракции, чтобы сформулировать это для себя — и так нам хочется сформулировать это и для других. Но просто это не то, как работает обучение и успешное наставничество.

Предоставляйте минимально необходимые объяснения ​

Если ученику не нужно объяснение, чтобы завершить руководство, не объясняйте.

Например, достаточно сказать что-то вроде "Мы используем HTTPS, потому что это более безопасно". Есть место для расширенной дискуссии и объяснений про HTTPS, но это не руководство. Иногда даже такое количество пояснений — больше, чем необходимо.

Может показаться проблематичным, что мы просим пользователя делать вещи без особых объяснений почему. На практике для ученика это редко таково. Обучающийся сфокусирован на следовании вашим указаниям и получении результата. Их время хотеть узнать больше о том "почему" они что-то делают прийдет позже. Любыми средствами включайте ссылки на дальнейшие поясняющие материалы, если считаете это необходимым, но постарайтесь преодолет соблазн перебить поток руководства отвлечениями на объяснения.

Игнорируйте опции и альтернативы ​

Ваша задача — провести ученика к успешному завершению. На пути могут быть интересные ответвления (разные опции используемой команды, разные применения API, разные подходы к описываемой задаче) — игнорируйте их. Ваши указания должны быть сфокусированы на том, что необходимо для достижения завершения, а все остальное можно оставить на другой раз.

Это помогает вашему руководству оставаться короче и четче, а также защищает вас и вашего читателя от излишней когнитивной работы.

Язык руководств ​

В этом руководстве вы сделаете... — описывайте то, что ученик выполнит (не "вы узнаете...").

Сначала сделайте Х. Теперь сделайте У. После того, как вы сделали У, выполните Z. — Нет места для неоднозначности и сомнений.

Мы должны всегда делать Х перед У потому что... (смотрите Объяснения для подробностей) — Предоставьте минимальные объяснения действий самым простым языком. Дайте ссылку на более детальное объяснение.

Результат должен выглядеть примерно так... — Формируйте у ваших учеников четкие ожидания.

Заметьте, что... Запомните, что... — Дайте обучающемуся множество подсказок, чтобы помочь подтвердить, что он на правильном пути и суметь сориентироваться в процессе.

Вы создали безопасный, трехслойный гиломорфный стазисный двигатель... — Опишите (и слегка восхититесь) то, что ученик выполнил. (не "Вы выучили...")