Как я веду и публикую JavaNotes
JavaNotes начался не как курс. Когда я учился программировать, мне требовалось место, куда можно вернуться после занятия или практики и быстро восстановить тему. Я записывал определения, вопросы, примеры кода и связи между понятиями в Obsidian.
Со временем отдельные файлы превратились в личную систему контекста:
вопрос
→ короткий ответ
→ механизм
→ соседняя тема
→ пример
→ реальный случайПоэтому я сохраняю и длинные обзорные заметки, и маленькие карточки. Они решают разные задачи: обзорная страница помогает вспомнить карту темы, атомарная — быстро найти конкретное отличие или правило.
Почему Obsidian
Мне подошёл формат обычных Markdown-файлов:
- заметки не заперты в одном сервисе;
- ссылки
[[между заметками]]образуют граф; - поиск работает по всей базе;
- историю можно хранить в Git;
- файлы читаются без Obsidian;
- хранилище легко скопировать и переделать.
Я не стараюсь превратить базу в линейный учебник. Главная точка входа — карта, а дальше маршрут зависит от вопроса.
Почему я открыл репозиторий
Когда база стала полезной мне, я решил выложить её на GitHub. Идея была не в том, чтобы объявить заметки окончательной истиной. Мне хотелось показать рабочую основу, которую другой разработчик может забрать, сократить, расширить и перестроить под себя.
На формат повлияла идея публичной базы знаний: показывать не только законченные статьи, но и саму растущую систему заметок.
Как устроена публикация
Obsidian vault остаётся источником заметок, а Git хранит историю изменений. Публичная версия находится на GitHub: там Markdown можно читать прямо в репозитории, клонировать и открывать в Obsidian.
Перед публикацией GitHub Actions запускает проверку vault: ищет битые Obsidian-ссылки, потерянные вложения и другие ошибки структуры. Это позволяет не превращать автоматизацию в отдельную инфраструктуру — workflow проверяет содержимое, но не подключается к внешнему серверу.
Публичный сайт собирается через Quartz и GitHub Pages:
Obsidian → Git → Quartz → GitHub PagesQuartz понимает Obsidian-ссылки и превращает связанный vault в обычный
статический сайт. GitHub Actions запускает сборку после изменений в main,
а исходные Markdown-файлы остаются пригодными для работы в Obsidian.
Как появляется новая заметка
Обычно отправная точка — конкретный вопрос:
- почему механизм повёл себя именно так;
- чем похожие интерфейсы отличаются;
- где проходит транзакционная граница;
- какой ответ я не смог уверенно дать на собеседовании;
- какую ошибку пришлось разбирать в коде или окружении.
Сначала я записываю факты и минимальный пример. Потом добавляю ссылки на базовые понятия. Если тема повторяется в работе, оформляю отдельный кейс.
Как публикую рабочий опыт
Я оставляю техническую суть и свой вклад, но убираю:
- названия работодателей, клиентов и внутренних продуктов;
- имена людей;
- номера задач и закрытых репозиториев;
- адреса, токены, ключи и фрагменты конфигурации окружения;
- доменные правила, по которым можно восстановить конкретную систему;
- исходный код, принадлежащий рабочему проекту.
Публичный кейс должен объяснять, что произошло, как я нашёл причину и что изменил. Он не должен быть копией производственного кода.
Правило для чужих материалов
Если источник помог мне разобраться, я пересказываю механизм своими словами и проверяю его на небольшом собственном примере. Дословный фрагмент отмечаю как цитату только тогда, когда он действительно нужен и его можно корректно атрибутировать.
Учебные скриншоты и иллюстрации с неизвестной лицензией в публичной базе не нужны. Схему, без которой теряется смысл, лучше заново выразить текстом, таблицей, кодом или Mermaid.
Что считаю хорошей заметкой
После перерыва я должен суметь:
- за минуту восстановить основное определение;
- объяснить механизм, а не только повторить термин;
- увидеть ограничение или частую ошибку;
- перейти к соседней теме;
- ответить на типичный вопрос собеседования;
- вспомнить случай, где знание пригодилось.
Это и есть критерий JavaNotes: заметка помогает снова войти в контекст.