Заметки, которые не теряют актуальности: составляйте заметки, которые приносят всё большую пользу с течением времени

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

Проблема не в усилиях. Инженеры постоянно пишут — комментарии в коде, сообщения в Slack, страницы в Confluence, описания в Jira, объяснения в pull request, диаграммы архитектуры. Проблема в том, что большинство этих заметок пишутся для конкретного момента и быстро устаревают. Они не накапливают ценность. Они просто копятся.

Вечнозеленые заметки (evergreen notes) — это альтернатива. Идея проста: пишите каждую заметку так, чтобы она оставалась полезной неопределенно долго, улучшалась при повторном просмотре и соединялась с другими заметками таким образом, чтобы вся система становилась более ценной со временем.

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

Что делает заметку вечнозеленой

Атомарность

Вечнозеленая заметка содержит одну идею. Не одну тему — одну идею.

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

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

Самодостаточность

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

Это означает, что нужно писать своими словами. Заметка, которая гласит «Смотрите связанную статью — там хорошие вещи про кэширование», не является вечнозеленой. Заметка, которая гласит «Кэширование write-through обновляет кэш синхронно с базой данных при каждой записи, улучшая согласованность чтения ценой более высокой задержки записи», является вечнозеленой. Вы можете прочитать ее через год, не пытаясь найти первоисточник.

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

Эволюция

Вечнозеленые заметки улучшаются со временем, а не устаревают.

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

Слово «вечнозеленая» намеренно: эти заметки не умирают после «сбора урожая». Они сохраняются и улучшаются.

Типы заметок и когда использовать каждый

Понимание вечнозеленых заметок требует понимания того, чем они не являются.

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

Литературные заметки — это резюме внешних источников — страницы документации, постмортем, главы книги, доклады с конференций. Литературные заметки сохраняют то, что сказал источник. Это шаг к пониманию, а не само понимание. Литературная заметка говорит: «этот источник утверждает X». Вечнозеленая заметка говорит: «Я верю в X по следующим причинам».

Вечнозеленые заметки синтезируют то, что вы поняли. Они находятся на выходе процесса обучения, а не на входе.

Написание вечнозеленых технических заметок

Структура хорошей вечнозеленой технической заметки следует простой логике: утверждение, доказательства, следствия.

# Кэширование write-through улучшает согласованность чтения ценой задержки записи

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

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

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

Ссылки:
- [[Кэширование read-through переносит заполнение кэша на время чтения]]
- [[Инвалидация кэша — это проблема координации]]
- [[Кэширование write-behind обменивает согласованность на пропускную способность записи]]

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

Чего следует избегать

Ссылки, чувствительные к времени, быстро устаревают. «По состоянию на Postgres 14 это поведение работает так» — это литературная заметка, а не вечнозеленая. Напишите принцип вместо этого: «Оптимизатор пропускает сканирование по индексу, когда оценочное количество строк превышает порог относительно размера таблицы». Это утверждение выживает при изменении версий, даже если порог меняется.

Команды, специфичные для инструментов, без контекста — это фрагменты, а не заметки. Заметка, которая состоит только из команды kubectl, скопированной с ответа на StackOverflow, не является вечнозеленой. Заметка о том, почему эта команда работает — какой ресурс Kubernetes она затрагивает и какую проблему решает — имеет шансы на успех.

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

Хорошие кандидаты на вечнозеленые заметки в инженерии

Почти любой сложно добытый урок с широким применением является хорошим кандидатом:

• Архитектурные компромиссы и обоснование решений
• Паттерны отладки, применимые к различным системам
• Правила проектирования API и их граничные случаи
• Характеристики производительности с привязкой к реальным цифрам
• Предположения о безопасности, которые оказались неверными
• Уроки стратегии тестирования из проектов, где подход провалился
• Ограничения развертывания, которые изменили работу команды

Общая черта: достаточно конкретная, чтобы быть применимой, достаточно общая, чтобы применяться более одного раза.

Рабочий процесс вечнозеленых заметок

Шаг 1: Фиксация мимолетных заметок

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

Во время сеанса отладки:

Обнаружил, что кэш возвращал устаревшие разрешения пользователей после изменения ролей.
TTL составлял 5 минут, но обновление роли было мгновенным.
Нужно продумать, как это обрабатывать — инвалидация при записи?
Или более короткий TTL? Или обновление на основе событий?

Это мимолетная заметка. Это не вечнозеленая заметка, но она содержит семена нескольких таких.

Шаг 2: Обработка во вечнозеленые заметки в течение 48 часов

Именно на этапе обработки появляется ценность. Возьмите сырую фиксацию и извлеките из нее идеи, которые стоит сохранить.

Из этой заметки об отладке вы можете написать:

# Записи кэша на основе ролей требуют инвалидации при записи, а не только истечения TTL

Когда кэшированные данные кодируют разрешения или роли, истечение на основе TTL небезопасно.
Пользователь, чья роль понижена, сохраняет повышенные разрешения до истечения TTL.
Инвалидация во время записи — или обновление кэша на основе событий при изменении роли — требуется
для корректности в кэшах, чувствительных к разрешениям.

Ссылки:
- [[Инвалидация кэша — это проблема координации]]
- [[Решения об авторизации не следует кэшировать в состоянии покоя без валидации]]

Контекст отладки исчез. Переносимая идея остается.

Шаг 3: Связывание с существующими заметками

После написания заметки потратьте две минуты, чтобы спросить:

• К какой существующей заметке это относится?
• От какой концепции это зависит?
• Что это расширяет или противоречит?

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

Шаг 4: Возвращение и улучшение

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

Вы можете:

• Добавить более конкретный пример
• Обновить утверждение на основе новых доказательств
• Убрать оговорку, которая оказалась неважной
• Добавить ссылку на новую связанную заметку
• Переписать первое предложение для ясности

Этот цикл уточнения — то, что делает заметки накапливающимися, а не деградирующими.

Вечнозеленые заметки и документация

Существует полезное различие между личными вечнозелеными заметками и командной документацией.

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

Командная документация предназначена для общего понимания. Ей нужна точность, доступность и ответственность за поддержку.

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

Направление потока обычно такое: вечнозеленые заметки → отполированная документация, а не наоборот.

Вечнозеленые заметки и системы RAG

По мере того, как инструменты знаний, дополненные ИИ, становятся более практичными, хорошо написанные вечнозеленые заметки становятся все более ценными в качестве исходного материала для извлечения. Проблема извлечения по сравнению с представлением в управлении знаниями по сути связана с качеством исходного материала — и вечнозеленые заметки, будучи атомарными, самодостаточными и написанными для понимания, хорошо подходят для разбиения на чанки (chunking) для векторного поиска.

Зеттелькастен (Zettelkasten) из атомарных вечнозеленых заметок является естественной основой для персональной системы RAG. Атомарная структура совпадает с размером чанка для извлечения. Самодостаточное свойство означает, что извлеченные заметки не требуют дополнительного контекста для полезности. Структура связей предоставляет возможности для обхода графа, выходящие за рамки поиска по ключевым словам.

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

Распространенные ошибки

Слишком широкое написание

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

Слишком узкое написание

Заметка, слишком специфичная для одного контекста, не имеет ценности для повторного использования. «Исправил баг кэширования сервиса биллинга 2024-03-14» — это запись в журнале, а не вечнозеленая заметка. Повысьте уровень абстракции, пока идея не будет применяться как минимум в трех разных контекстах.

Путаница «вечнозеленого» и «никогда не меняющегося»

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

Пропуск этапа обработки

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

Инструменты

Obsidian

Obsidian — самый популярный инструмент для вечнозеленых заметок. Его локальные файлы Markdown, двусторонние ссылки и графический вид хорошо сочетаются с этой практикой. Простая структура:

vault/
  fleeting/
    daily/
  literature/
  evergreen/
  maps/       ← заметки-индексы для кластеров вечнозеленых заметок

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

Обычный Markdown с Git

Репозиторий Git с файлами Markdown работает хорошо и не зависит от какого-либо конкретного инструмента. Стандартные ссылки Markdown соединяют заметки. Поиск обрабатывается вашим редактором или grep. История версий поступает из Git.

knowledge/
  evergreen/
    caching/
    api-design/
    performance/
  literature/
  fleeting/

Дисциплина одинакова независимо от инструмента — одна идея на заметку, написанная вашими словами, связанная с другими заметками.

Начало с нуля

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

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

Это и есть полная вечнозеленая заметка. Повторяйте раз в неделю в течение шести месяцев, и у вас будет рабочая система.

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

Финальные мысли

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

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

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