Объяснения¶

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

Объяснение углубляет и расширяет понимание предмета. Оно проясняет его, освещает и помещает в контекст.

Понятие осмысления здесь особенно важно. Оно происходит вслед за чем-то другим и опирается на это, но при этом привносит новое — по-новому освещает предмет.

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

Для пользователя объяснение связывает отдельные сведения воедино. Оно отвечает на вопрос: Можете рассказать о…?

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

Ценность и место объяснений¶

Объяснение и понимание¶

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

Английское слово explanation и однокоренные слова в других языках отсылают к разворачиванию — раскрытию того, что скрыто в складках. Таким образом, объяснение выводит на свет то, что оставалось неявным или затемнённым.

Так же и слова со значением понимания имеют общие корни со словами, означающими «держать» или «схватывать» (как в слове постигать). Это важная сторона понимания: мы можем охватить нечто умом и сделать своим. Понимание скрепляет остальные составляющие нашего мастерства и позволяет уверенно ими владеть.

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

Объяснение и его границы¶

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

Написать хороший объясняющий материал не всегда легко. С чего начать? Где закончить? У объяснений нет естественного предела, и перед автором открывается слишком много возможностей.

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

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

Как писать хорошие объяснения¶

Устанавливайте связи¶

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

Предоставьте контекст¶

Раскрывайте в объяснении предысторию и контекст: объясняйте, почему всё устроено именно так, — рассказывайте о проектных решениях, исторических причинах и технических ограничениях; формулируйте следствия и приводите конкретные примеры.

Говорите о предмете¶

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

Допускайте мнения и разные точки зрения¶

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

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

В объяснении вы не даёте инструкций и не перечисляете факты — вы открываете тему для рассмотрения. Полезно относиться к объяснению как к обсуждению: в обсуждении можно рассмотреть и взвесить даже противоположные мнения.

Чётко ограничивайте рамки объяснения¶

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

Язык объяснения¶

Причина x в том, что исторически y…: Объясняйте.
W лучше, чем z, потому что…: Высказывайте суждения и даже мнения, когда это уместно.
x в системе y аналогичен w в системе z. Однако…: Обеспечьте контекст, который поможет читателю.
Некоторые пользователи предпочитают w (потому что z). Это может быть хороший подход, но…: Взвесьте альтернативы.
x взаимодействует с y следующим образом: …: Раскрывайте внутреннее устройство системы, чтобы читатель понимал, почему она ведёт себя именно так.

Аналогия с едой и кулинарией¶

В 1984 году Гарольд МакГи опубликовал О еде и кулинарии.

Эта книга не учит готовить конкретные блюда. В ней нет рецептов, кроме исторических примеров, и это не справочник. Вместо этого книга помещает пищу и кулинарию в контекст истории, общества, науки и технологии. Например, она объясняет, почему мы действуем на кухне именно так и как эти практики менялись.

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

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