2learn

Техническое письмо

Что это такое

Техническое письмо — это документация, по которой может пройти незнакомый человек: спецификации, README, инструкции по эксплуатации, заметки об архитектуре и записи решений. Артефакт — сам документ, и единственная проверка, которая имеет значение, — может ли тот, кто его не писал, действовать по нему, не задав ни одного вопроса.

Почему это важно

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

Что в этом треке

  1. Структура спецификации или README (04-product-process/08-technical-writing/01-structure-of-a-spec-or-readme) — какие разделы читатель ждёт и в каком порядке они ему нужны.
  2. Редактирование для читателя (04-product-process/08-technical-writing/02-editing-for-the-reader) — как сокращать, упорядочивать и проверять документ на ком-то, кто не вы.

Предварительные требования

Нет.

Что читать дальше

Файлы cookie аналитики ставятся только с вашего согласия. До вашего выбора ничего не загружается и никуда не отправляется.