Объяснения¶

Объяснение – это дискурсивная трактовка предмета, допускающая отражение. Пояснение: ориентированный на понимание.

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

Концепция отражение важна. Рефлексия происходит после в чем-то другом и зависит от чего-то другого, но в то же время вносит что-то новое - проливает новый свет - на предмет.

Перспектива объяснения выше и шире, чем у остальных трех типов. Он не учитывает вид с уровня глаз пользователя, как в практическом руководстве, или вид оборудования крупным планом, как в справочном материале. Его сферой в каждом случае является тема – «область знаний», которая должна каким-то образом разумно и осмысленно быть ограничена.

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

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

Значение и место объяснения¶

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

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

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

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

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

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

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

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

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

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

Написание хорошего объяснения¶

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

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

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

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

Обсудите о тему¶

Пояснительные руководства являются о темой в том смысле, что они являются вокруг ею. Даже названия ваших пояснительных руководств должны отражать это; вы должны иметь возможность поместить неявный (или даже явный) о перед каждым заголовком. Например: Об аутентификации пользователя или О политиках подключения к базе данных.

Признайте свое мнение и точку зрения¶

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

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

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

Держите объяснение строго ограниченным¶

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

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

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

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

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

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

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

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