Примеры зачастую полезнее объяснений

Я тут осознал, что сильно недооценивал роль примеров (examples) для технической документации. Документация очень сильно выигрывает от хороших примеров. Продуманные примеры могут быстро сориентировать читателя – ввести в курс дела, и облегчить понимание более детального описания. Более того, хорошо подобранные примеры способны сходу предоставить читателю (= пользователю) решение конкретной проблемы, без необходимости вообще вникать в детали. Вообще, кажется, есть много сценариев, где наиболее практичная документация == правильно подобранный набор примеров с краткой аннотацией.

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

Никто не читает документацию

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

Если аккуратнее: никто не любит читать документацию, никто не любит искать ответы на свои вопросы в документации.

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

Умение понятно писать – один из самых недооцененных инженерных навыков

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

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

Конечно, есть миллион других навыков, которые не помешали бы инженеру, но я выделяю этот, потому что это low hanging fruit: большинство инженеров уже умеют думать, и уже хорошо разбираются в предмете. Не хватает, по-моему, малого – немного научиться думать о читателе.

What makes a rule complex (for brain): mechanical sympathy applied to humans

Интересная статья 2020 года: "What makes a rule complex?". Что делает правило (алгоритм) сложным для выполнения человеческим мозгом?¹

Мы часто оцениваем стоимость выполнения алгоритма: на какой-то абстрактной машине, или на реальном железе (конечном автомате, машине Тьюринга, Intel Core i7…). А что насчет человеческого мозга? Если смотреть на мозг как вычислительную машину, и скармливать ему разные "программы" – описания алгоритмов на человеческом языке – то насколько "дорого" для мозга будет выполнить действия соответственно описанию? Как цена выполнения алгоритма мозгом будет зависеть от устройства алгоритма?

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

Рабочие заметки в помощь мозгу

Давно уже хотел написать об этом, но только сейчас дошли руки:

Комрады! Пишите рабочие заметки – о чем вы думаете, над чем работаете – особенно если думаете о чем-то достаточно сложном. Это очень, очень, очень помогает думать! (И не только думать)

Вот уже несколько лет я практически все рабочие и личные задачи обсуждаю с большим файлом notes.txt (notes.org). Этот файл решает сразу несколько задач:

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