Различие между учебным и практическим руководством¶
В Diátaxis учебные и практические руководства чётко разграничены. Часто это различие вообще не проводят; более того, в документации программных продуктов чаще всего смешивают именно учебное руководство и практическое руководство.
Итак, в чём состоит различие между учебными и практическими руководствами? Почему оно важно? И почему эти два типа путают?
Все эти вопросы уместны. Начнём с последнего: если различие действительно так важно, почему оно не очевиднее?
Что у них общего¶
Во многих существенных аспектах учебные и практические руководства похожи. Оба имеют практический характер: содержат указания, которым следует пользователь. Их задача не в том, чтобы что-либо объяснять или сообщать информацию. Они помогают пользователю действовать, а не узнавать или понимать.
Оба типа излагают шаги для читателя и обещают: если следовать этим шагам, всё закончится успешно. Оба почти бессмысленны для пользователя, который не работает с системой непосредственно и не готов действовать. Оба описывают упорядоченные последовательности действий: на успех нельзя рассчитывать, если выполнять их не в том порядке.
Они близки, а близких родственников при первом знакомстве легко перепутать.
Важно то, что нужно пользователю¶
Diátaxis утверждает, что в документации важны потребности пользователя. Внимание к этим потребностям и позволяет правильно различать учебные и практические руководства.
Иногда пользователь учится, а иногда работает. Документация должна удовлетворять обе потребности.
Учебное руководство отвечает потребностям пользователя во время обучения. Оно обязано обеспечить успешный учебный опыт. Практическое руководство отвечает потребностям пользователя во время работы. Оно обязано помочь пользователю выполнить задачу. Это совершенно разные потребности и обязательства — вот почему важно различать эти два типа: учебные руководства ориентированы на обучение, а практические — на выполнение задач.
Во время обучения и во время работы¶
Рассмотрим конкретный пример. Допустим, вы врач: вам нужно и приобретать, и применять практические клинические навыки своей профессии.
Иногда вы как врач оказываетесь в рабочей ситуации и применяете навыки, а иногда — в учебной и приобретаете навыки. Все хорошие врачи, даже после многих лет практики, продолжают учиться и совершенствовать своё мастерство.
Во время обучения¶
В начале подготовки вы научитесь ушивать рану. Занятие пройдёт в лаборатории вместе с другими студентами. Перед каждым на столе будет небольшой муляж кожи — блок из нескольких слоёв синтетического материала, изображающих эпидермис, жировую ткань и другие ткани. По твёрдости и фактуре он похож на человеческую плоть и при разрезании и наложении швов ведёт себя сходным образом. Вам выдадут всё необходимое: перчатки, скальпель, иглу, нить и так далее. Затем шаг за шагом покажут, что делать и что будет происходить.
А потом наступит ваша очередь. Вы возьмёте скальпель, нерешительно проведёте им по поверхности муляжа и оставите слишком поверхностный надрез в верхнем слое. Возможно, ассистент преподавателя поддразнит вас: чем же этот бедный муляж заслужил такую скверную царапину? Ваш сосед с ужасом посмотрит на собственный результат — рваный разрез, глубина которого резко меняется, словно после драки на ножах.
После нескольких попыток, получая замечания и поправки преподавателя, вы сделаете более или менее аккуратный разрез, который большей частью пройдёт через жировой слой, не задев лежащую под ним мышцу. Победа!
Но теперь вас просят снова зашить разрез! Вы увидите, как преподаватель ловко и точно закрывает рану на муляже несколькими аккуратными ровными швами. Сами же вы будете путаться в нити, брать инструменты не той рукой и не с той стороны, класть их не туда. Вы уроните иглу. Нить выскользнет из неё. Вас отчитают за нарушение стерильности.
Наконец вы сами приступите к ушиванию раны. Вы проколете кожу не там, где нужно, и надорвёте края разреза. В итоге получится неприглядная картина: растянутая, сморщенная кожа и грубые неровные стежки. Ассистенты преподавателя найдут что покритиковать даже в тех местах, которые вы считали удачными.
Но вы наложили швы на свою первую рану. Вы ещё не раз вернётесь к этому уроку, и мало-помалу неуверенные движения станут уверенными и отработанными. Вы приобретёте базовую компетентность — научитесь на практике.
Это учебное руководство. Это урок под надёжным руководством преподавателя, который заботится об интересах ученика.
На работе¶
Теперь рассмотрим врача за работой. Вы уже компетентный специалист: освоили и отточили наложение швов и многие другие клинические навыки и каждый день сочетаете и применяете их в реальных медицинских ситуациях.
Возьмём стандартную аппендэктомию. В клиническом руководстве перечислены оборудование и персонал, необходимые в операционной. Оно показывает, как разместить членов бригады и расположить инструменты, стойки и мониторы. Затем шаг за шагом описывает действия бригады, вплоть до официальной передачи пациента послеоперационной команде.
Руководство укажет, где и какие разрезы нужно сделать, но они будут зависеть от выбранного доступа — открытого или лапароскопического, наличия результатов предоперационной визуализации и других условий. Для младенцев и детей, а также при переходе к открытой аппендэктомии в ходе операции предусмотрены особые шаги или проверки. Многие указания имеют форму если выполняется такое условие, сделайте то-то.
Руководство помогает выполнить все шаги в правильном порядке и ничего не пропустить. Вся команда сверяется с описанием процедуры, чтобы освежить в памяти ключевые этапы; иногда к нему обращаются и во время самой операции.
Даже для рутинных хирургических операций клинические руководства содержат списки шагов и проверок. Это практические руководства. Они не учат вас: необходимые навыки у вас уже есть, и процессы вам известны. Они помогают безопасно выполнить конкретную задачу в клинической практике — они помогают вам в работе.
Понимание различия¶
Различие между уроком в медицинском вузе и клиническим руководством — это различие между учебным и практическим руководством.
Цель учебного руководства — помочь ученику приобрести базовую компетентность.
Цель практического руководства — помочь уже компетентному пользователю правильно выполнить конкретную задачу.
Учебное руководство обеспечивает учебный опыт. Люди осваивают навыки на практике, собственными руками. В учебном руководстве важно, что учащийся делает и какой опыт при этом получает.
Практическое руководство направляет работу пользователя.
Учебное руководство ведёт по тщательно контролируемому пути от заданной исходной точки к завершению. На этом пути учащийся должен получить тот опыт взаимодействия, который предусмотрен уроком.
Практическое руководство нацелено на успешный результат и ведёт пользователя к цели самым безопасным и надёжным маршрутом. Но контролировать этот путь невозможно: всё происходит в реальном мире, где что угодно может нарушить ход работы.
Учебное руководство знакомит учащегося с работой: с инструментами, языком и процессами, с поведением и реакциями объекта работы и так далее. Его задача — представить всё это учащемуся, организовав структурированное и воспроизводимое знакомство.
Практическое руководство может и должно исходить из того, что пользователь со всем этим знаком.
Работа с учебным руководством проходит в искусственно созданной обстановке — учебной среде, где как можно больше условий задано заранее, чтобы обучение прошло успешно.
Практическое руководство предназначено для реального мира, где приходится иметь дело со всем, что он преподносит.
Учебное руководство исключает неожиданности.
Практическое руководство должно готовить к неожиданностям: предупреждать пользователя о том, что они возможны, и объяснять, как с ними справиться.
Учебное руководство ведёт по одной линии. Оно не предлагает вариантов или альтернатив.
Практическое руководство обычно разветвляется, описывая разные пути к одной цели: Если это, сделайте то. В случае… используйте другой подход…
Учебное руководство должно быть безопасным. Учащийся не должен пострадать; у него всегда должна быть возможность вернуться к началу и попробовать снова.
Практическое руководство не может гарантировать безопасность: часто у пользователя есть лишь одна попытка всё сделать правильно.
В учебном руководстве ответственность лежит на учителе. Если учащийся столкнулся с затруднением, исправить ситуацию должен учитель.
В практическом руководстве ответственность лежит на пользователе: он сам отвечает и за возникшие затруднения, и за выход из них.
Учащемуся может не хватать компетентности даже для того, чтобы задать вопросы, на которые отвечает учебное руководство.
Практическое руководство может исходить из того, что пользователь изначально задаёт правильные вопросы.
Учебное руководство явно описывает базовые вещи: где выполнять действия, куда класть предметы, как обращаться с объектами. Оно учитывает телесный опыт: в нашем медицинском примере — с какой силой нажимать и как держать инструмент; в руководстве по программному обеспечению — где вводить команду или как долго ждать ответа.
Практическое руководство опирается на всё это как на неявное знание, в том числе телесное.
Подход учебного руководства конкретен и ориентирован на частный случай. Оно опирается на конкретные, известные и чётко заданные инструменты, материалы, процессы и условия, которые мы тщательно подготовили для учащегося.
Практическому руководству необходим общий подход: многие из этих факторов заранее неизвестны или различаются от случая к случаю в реальном мире.
Учебное руководство обучает общим навыкам и принципам, которые позднее можно применять во множестве ситуаций.
Пользователь обращается к практическому руководству, чтобы выполнить конкретную задачу.
Ни одно из этих различий не произвольно. Все они следуют из различия между обучением и работой — ключевого различия, без которого невозможно понять потребности пользователя документации.
Базовое и продвинутое¶
Распространённая и понятная ошибка — считать различие между учебными и практическими руководствами различием между базовым и продвинутым.
На первый взгляд всё логично: учебные руководства предназначены для учащихся, а практические — для уже квалифицированных специалистов. Учебные руководства должны излагать основы, тогда как практическим приходится разбирать сложности, с которыми учащимся сталкиваться не следует.
Однако этим дело не ограничивается. Возьмём руководство по клиническим процедурам: оно может описывать простую рутинную процедуру минимальной сложности — например, правильное оформление документов или утилизацию определённых материалов. Практические руководства не только могут, но и нередко должны описывать базовые процедуры.
В то же время даже квалифицированный врач снова и снова оказывается в учебных ситуациях. Некоторые из них бывают весьма продвинутыми и узкоспециализированными и уже для участия требуют высокого уровня навыков и опыта.
Представьте, что вы анестезиолог с многолетним стажем и пришли на курс «Сложные интубации у новорождённых». Практическая часть курса даст вам учебный опыт: под надёжным руководством преподавателей вы будете выполнять упражнения и развивать навыки — так же, как много лет назад, когда учились ушивать свою первую рану.
Сложность здесь совсем иная, как и исходный уровень навыков, необходимый даже для участия. И всё же по форме и по потребности, которой он служит, этот урок такой же, как тот давний.
То же верно для документации программного обеспечения: учебное руководство может знакомить со сложной или продвинутой темой, а практическое — описывать что-то базовое или общеизвестное. Различие между ними определяется потребностью пользователя, которой они служат: учиться или работать.
Безопасность и успех¶
Понимание этих различий и причин, по которым их важно соблюдать, критично для создания успешной документации. Клиническое руководство, которое смешивает обучение с практикой и пытается одновременно учить и сопровождать реальную процедуру, станет в буквальном смысле смертельно опасным документом. Оно будет убивать людей.
В таких областях, как документация программного обеспечения, нам многое сходит с рук, потому что путаница и наши ошибки редко кого-либо убивают. Но мы способны причинить пользователям множество мелких неудобств и огорчений — и делаем это всякий раз, когда публикуем учебное или практическое руководство, автор которого не разобрался, чему оно должно помогать: обучению — приобретению навыков — или работе — применению навыков.
Более того, мы вредим и себе. Пользователи не обязаны выбирать наш продукт. Если документация не приводит их к успеху — не отвечает потребностям на конкретном этапе взаимодействия с продуктом, — они по возможности найдут другой продукт, который с этим справится.
Учебные и практические руководства — далеко не единственные виды документации, которые смешивают, но перепутать их особенно легко. Эта ошибка к тому же особенно вредна: она способна оттолкнуть новичков, которых мы надеемся превратить в постоянных пользователей. Ради них и ради собственного продукта важно провести это различие правильно — это один из ключей к успеху.