Различие между справочником и объяснением¶
Объяснения и справочная документация относятся к теоретической половине карты Diátaxis: в них нет последовательностей шагов, ведущих читателя, — они содержат теоретические знания.
Различие между ними — как и различие между учебными и практическими руководствами — состоит в том, направлен ли материал на приобретение знаний и навыков или на их применение. Иными словами, это различие между учёбой и работой.
Простое различие, в основном¶
В большинстве случаев довольно легко понять, с каким из двух типов вы имеете дело. Справочная документация как форма текста хорошо знакома: мы учимся отличать её от других форм письма ещё в раннем возрасте.
Кроме того, многие тексты сами по себе явно относятся к одному из этих типов. Таблица приливов с рядами чисел — очевидный справочный материал. Статья о том, почему возникают приливы и как они себя ведут, — очевидное объяснение.
Есть несколько полезных практических ориентиров:
Если материал скучен и не запоминается, скорее всего, это справочник.
Списки сущностей (например, классов, методов или атрибутов) и таблицы данных, как правило, относятся к справочной документации.
С другой стороны, если вы можете представить, что читаете этот текст в ванной, вероятно, это объяснение (хотя читательские привычки в ванной бывают самыми разными).
Представьте, что на прогулке или за бокалом вы спрашиваете друга: Можешь рассказать подробнее о <теме>? Скорее всего, последующий ответ или разговор будет её объяснением.
…но одной интуиции недостаточно¶
Обычно различать справочную документацию и объяснения можно интуитивно. Но лишь обычно: одна форма текста довольно легко переходит в другую.
Обычно это происходит, когда справочный материал начинает разрастаться. Например, включать в справочник наглядные примеры вполне уместно — так же как включать иллюстрации в энциклопедию. Но развивать примеры увлекательно, поэтому возникает соблазн превратить их в объяснения: рассказать с их помощью, почему всё устроено именно так, что будет, если… или как всё к этому пришло.
В результате объяснительный материал нередко оказывается рассыпан по справочнику. Справочник от этого страдает: отступления прерывают и затуманивают описание. Страдает и само объяснение, потому что ему не дают полноценно раскрыться и выполнить свою задачу.
Работа и учёба¶
Если мы всё же сомневаемся, должен ли материал быть справочником или объяснением, есть надёжный способ проверить. Обратится ли к нему человек прямо во время работы — когда он занят делом и выполняет задачу? Или он понадобится после того, как человек отложит работу и захочет её осмыслить?
Это две принципиально разные потребности читателя. Они отражают его отношение к своему делу в данный момент: он либо работает, либо учится.
Справочная документация нужна пользователю, чтобы применять знания и навыки во время работы.
Объяснение помогает человеку приобретать знания и навыки — то есть учиться.
Понимание этих двух способов взаимодействия с предметом и связанных с ними потребностей — ключ к созданию эффективных справочников и объяснений.