Hacker News Digest

Diátaxis — это системный подход к созданию технической документации, основанный на четырёх типах потребностей пользователей: учебники (tutorials), пошаговые инструкции (how-to guides), технические справочники (technical reference) и объяснения (explanation). Каждый тип решает конкретную задачу: от обучения новичков до углублённого понимания механизмов. Документация должна структурироваться вокруг этих четырёх форм, а не вокруг продуктов или технологий, что делает её более интуитивной и эффективной.

Методика не накладывает жёстких ограничений на формат или инструменты, но даёт чёткий принцип качества: каждая статья должна чётко соответствовать одной из четырёх категорий. Это упрощает работу авторов и поддержку документации. Практика подтверждает эффективность: компании вроде Vonage, Gatsby и Cloudflare перестроили свои документации по Diátaxis, что привело к росту удобства для пользователей и вовлечённости contributors. Участники отмечают, что структура помогает быстро находить нужный контент и решать, куда добавить новый материал.

Тред приводит примеры успешного применения Diátaxis в реальных проектах, подтверждая его эффективность в создании структурированной и удобной документации — так отмечают @conradludgate, @radicalriddler, @c0rruptbytes, @rkangel и @aeden. Указываются необходимость регулярного обновления документации и советы: тщательно изучить Diátaxis перед реализацией (@jamilbk) и использовать ссылки для поддержания актуальности (@CompoundEyes). Среди критики — дополнительные клики для доступа к информации (@rjmill) и мнение @voidhorse, что популярность Diátaxis обусловлена недостаточным распространением знаний о документации в техническом сообществе.

В 2026 году LLM стали полезны не потому, что стали умнее, а потому что научились надёжно работать в автоматизированных циклах обратной связи: они могут по запросу «сделать кнопку, которая делает X» и корректно определить, когда задача выполнена. Это даёт примерно 2x прирост производительности — достаточно, чтобы изменить работу, но не заменить программиста. Главное — LLM отлично справляются с чётко сформулированными, проверяемыми задачами, но не с оценками качества кода, архитектуры или документации.

Автор использует LLM для генерации черновиков, но тратит больше времени на их доработку, чем раньше на написание всего кода — теперь «рабочий» код — это лишь 20% задачи. Для документации он даёт чёткую инструкцию: «никогда не пишите README или комментарии — я сделаю это сам». Улучшения моделей вряд ли дадут 10x прирост, потому что фундаментальные ограничения — в способности понимать смысл, а не генерировать синтаксис — остаются. Будущее за перестройкой процессов: сандбоксы, декларативные спецификации, безопасные паттерны для «вайб-кодинга». Пока же — ручные README и тщательная доработка.

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

Cognition представила Windsurf Codemaps — AI-аннотированные структурные карты кода, которые помогают разработчикам понимать свои проекты перед тем, как вносить изменения. В отличие от большинства AI-инструментов, которые увеличивают разрыв между программистом и его кодом, Codemaps нацелены на углубление понимания. Как отмечает Пол Грэм: "Ваш код — это ваше понимание проблемы, которую вы исследуете. Только когда код у вас в голове, вы действительно понимаете проблему". Новая функция основана на SWE-1.5 и Claude Sonnet 4.5, предлагая два режима работы: быстрый и интеллектуальный.

Проблема понимания кода стоит остро: новым разработчикам требуется 3-9 месяцев для полного освоения проекта, а старшие специалисты тратят более 5 часов в неделю на помощь коллегам. По данным Stripe, поддержка легаси-кода — главный фактор, снижающий продуктивность. Codemaps решает эту задачу, позволяя создавать контекстные карты кода по запросу для конкретных задач. Это следующий шаг после Ask Devin и DeepWiki, делающий процесс онбординга и навигации по кодовой базе более эффективным.

• Обсуждение в основном вращается вокруг трёх тем: визуализация кода (CodeMaps), инструментов вроде Windsurf и Cursor, а также влияние LLM на понимание и навигацию по коду.
• Участники обсуждают, насколько полезны визуализации кода в больших кодовых базах и как они справляются с контекстом и бизнес-логикой.
• Также поднимается вопрос о том, что такие инструменты могут быть полезны для онбординга в новых кодовых базах, но критики утверждают, что без контекста эти визуализации не имеют ценности.
• Некоторые участники высказывают мнение, что вместо того, чтобы полагаться на визуализации, разработчики должны уделять внимание созданию и поддержанию хорошей документации.
• Обсуждение также затрагивает влияние инструментов на продуктивность и то, как они могут быть использованы в больших и сложных кодовых базах.

Митчелл Хашимото делится личным опытом, как не теряя мотивации довести большие проекты до конца. Он начинает с маленького, но ощутимого результата: например, вместо «сделать терминал» он берёт подпроект «распарсить VT-коды» и уже через пару дней имеет живой результат и тесты. Далее он итеративно добавляет новые фичи, каждый раз имея что-то, что можно показать. Это позволяет сохранять энтузиазм и не терять фокус. Под конец он напоминает, что не стоит стыдиться незавершённых проектов — главное, чтобы они были интересны самому автору.

• Собеседники подчеркнули, что ключ к быстрому прогрессу — это умение разбивать задачу на мелкие, легко демонстрируемые фрагменты и не застревать в «анализ-парализе»; главное — быстро получать обратную связь и не бояться «грязного» MVP.
• Подчеркнуто, что выбор инструмента (язык/стек) влияет на скорость итераций: REPL-языки и инструменты вроде hot-reload позволяют видеть эффект изменений почти мгновенно, что снижает порог входа и удерживает мотивацию.
• Участники обсуждения подтвердили: чем раньше показать работающий прототип, тем меньше вероятность, что проект застрянет в вечной «доработке»; демо-ориентированная разработка заставляет фокусироваться на ценности для пользователя, а не на перфекционизме.
• Сообщество отметило, что даже в личных проектах важно документировать и тестировать как будто ты передашь его другу: это упрощает возврат к контексту спустя месяцы и служит живым примером.
• Несколько человек поделились личным опытом, что их подход к разработке ПО вдохновил их начать вклад в open-source, и что их опыт в open-source в свою очередь улучшил их навыки ведения личных проектов.

Разработчики часто сталкиваются с тем, что официальная документация описывает функцию, но не показывает, как её использовать. Пример: вместо того, чтобы показать, как вызывать max() в Python, документация тратит абзацы на то, чтобы объяснить, что такое iterable и что значит key=. А ведь достаточно было бы показать, как передавать кастомную функцию сортировки в max().

Проект ClojureDocs берёт на себя роль «примеры — лучшая документация». Пользователи добавляют примеры к встроенным функциям, и это оказывается куда более полезным, чем формальное описание API. Примеры показывают, как вызывать функцию, какие есть подводные камни и какие есть альтернативы.

• Документация должна включать и примеры, и полное API-описание; оба формата дополняют, а не конкурируют.
• Примеры важны для новичков, но не заменяют полное описание параметров и контрактов; примеры без спецификации приводят к тому, что разработчики вынуждены читать исходники.
• Примеры должны быть живыми: если они не запускаются как часть CI или не покрыты тестами, они быстро устаревают и вводят в заблуждение.
• Документация должна быть двух типов: краткий пример для быстрого старта и полное руководство для продвинутых пользователей.
• Примеры должны быть частью тестов и наоборот: примеры в документации должны быть тестируемыми как часть CI.

Typst — это новая система вёрстки документов, написанная на Rust и позиционируемая как современная альтернатива LaTeX. Она сохраняет высокое качество вывода, особенно для технических и научных материалов с формулами, таблицами и иллюстрациями, но предлагает более простой синтаксис разметки, быстрое компилирование и удобную кастомизацию. Проект развивается с 2019 года, уже насчитывает сотни контрибьюторов и постепенно получает признание в академической среде.

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

• Пользователи отмечают значительное преимущество Typst перед LaTeX в скорости компиляции, удобстве синтаксиса и понятности диагностических сообщений.
• Многие перешли на Typst для генерации документов в продакшн-средах (инвойсы, отчёты, книги) благодаря его простоте интеграции с данными (JSON) и программируемости.
• Подчёркивается проблема принятия Typst в научном сообществе из-за доминирования LaTeX-шаблонов журналов и конференций, а также отсутствия полной поддержки инструментов вроде Zotero.
• Некоторые пользователи выражают скептицизм по поводу замены LaTeX для сложных математических формул и опасения по поводу долгосрочного развития и обратной совместимости Typst.
• Typst часто используется как замена Markdown для простых документов и заметок благодаря интуитивному формату и мгновенному предпросмотру.

Современные модели ИИ демонстрируют сверхчеловеческие способности в решении абстрактных задач, как показал недавний успех GPT-5 на ICPC, но автономные кодирующие агенты всё ещё не могут заменить разработчиков. Основное ограничение — не интеллект, а контекст: агентам не хватает глубокого понимания кодовой базы, её архитектурных паттернов и скрытых знаний, которые есть у людей.

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

• Основным ограничением для кодирующих агентов на основе ИИ является не размер контекстного окна, а неспособность эффективно фокусироваться на актуальных задачах и отбрасывать нерелевантную информацию.
• Многие участники отмечают, что ИИ-агенты демонстрируют уровень понимания, сравнимый с начинающим разработчиком, и не способны заменить senior-специалистов, которые могут интерпретировать бизнес-требования и принимать ответственные решения.
• Существует скептицизм относительно бесконечного увеличения "интеллекта" моделей, так как даже с большим контекстом они допускают ошибки и галлюцинации, а фундаментальные ограничения вероятностной генерации остаются.
• Предлагаются решения для улучшения работы агентов: лучше структурированные кодобазы, иерархическая документация, инструменты для управления контекстом и памятью, а также человеческий контроль для курирования процесса.
• Подчёркивается, что ключевая проблема — не технический контекст, а понимание intent (намерения) стоящего за кодом, что требует более глубокого осмысления, чем простое прогнозирование токенов.

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

Метод включает три этапа: определение проблемы, формулирование цели и анализ реальности. Коверт рекомендует начинать с «почему», затем переходить к «что» и только потом к «как», используя язык как инструмент для выражения намерений. Практические инструменты, такие как диаграммы и карты, помогают визуализировать и структурировать информацию, делая сложные системы управляемыми.

• Обсуждение подчеркивает важность инструментов визуализации, таких как диаграммы критического пути и графы зависимостей, для анализа сложных систем и процессов.
• Участники отмечают, что хаос и сложность часто возникают из-за плохой документации, низкого качества данных и взаимосвязанных проблем в системах.
• Многие комментарии критикуют дизайн сайта автора, называя его запутанным и трудным для восприятия, что отвлекает от содержания.
• Обсуждаются стратегии работы со сложностью: улучшение сигнал/шум, заимствование методик из других областей (авиация, OODA-петли) и принятие неизбежных "помоек".
• Модератор напоминает сообществу о правилах, призывая избегать непродуктивных жалоб на второстепенные раздражители, такие как формат сайтов.

Нетехнический пользователь сталкивается с типичной проблемой: туториал для начинающих написан разработчиком, который не учитывает реальный уровень новичка. Автор иронично описывает, как инструкция изобилует жаргонизмами вроде «Shoobababoo» и «Snarfus», предполагает знание скрытых системных папок и содержит запутанные команды терминала без пояснений. Ключевой момент — осознание, что даже после семи часов поисков и 193 запросов в интернете шаг «Boop!» кажется достижением, хотя суть решения остаётся непонятной. Практический вывод: обучающие материалы должны проверяться на реальной аудитории, иначе они превращаются в пародию, несмотря на благие намерения автора.

• Рекомендуется тестировать документацию на новичках или людях с минимальным опытом, наблюдая за их трудностями без помощи, чтобы выявить пробелы и неявные предположения.
• Многие руководства написаны разработчиками для других разработчиков в той же экосистеме и предполагают базовый уровень знаний, что может быть неочевидно для настоящих новичков.
• Проблема усугубляется "проклятием знания" — авторам сложно представить, что неизвестно читателю, что приводит к пропуску важных шагов, контекста и объяснения базовых концепций.
• Эффективная документация должна четко определять целевую аудиторию, предварительные требования, предоставлять конкретные примеры кода и работать в строго определенном окружении, чтобы избежать "гниения" инструкций.
• Решения включают в себя итеративную обратную связь от новых пользователей, удаление ненужного жаргона, использование интерактивных элементов и явное указание альтернатив для разных сред и инструментов.

Monodraw — редактор ASCII-графики для macOS (11 Big Sur+).
Пробная версия бесплатно, лицензия — $9.99, скидки для учебных заведений.

Возможности

• Диаграммы: структуры данных, алгоритмы, ER-диаграммы (нотация «Crow’s Foot»).
• Mind-map: свободное размещение текста на бесконечном холсте.
• Баннеры: 148 встроенных шрифтов FIGlet, изменение размера и выравнивание.
• Инструменты: прямоугольники, линии (ортогональные, лестницы), текст, карандаш, ластик, заливка, пипетка.
• Точки крепления: линии автоматически цепляются к фигурам.
• CLI: генерация документации в хуках Git, экспорт JSON.
• Группы, направляющие, фокус-режим, горячие клавиши для быстрой работы.

Экспорт: PNG, SVG.

• Разработчик Monodraw отвечает на вопросы; пользователи делятся альтернативами (asciiflow, textik, durdraw, REXPaint).
• Все хвалят чистоту результата, низкую цену ($10 навсегда) и удобство вставки ASCII-диаграмм прямо в код или документацию.
• Основные сценарии: комментарии в исходниках, схемы сетей, баннеры серверов, ASCII-анимации, план кухни.
• Главный недостаток: приложение только для macOS; много просьб портировать на Linux.
• Новая текстовая разметка (апрель 2025) улучшает работу с системами контроля версий.

Вместо «умных» функций — просто работающие.

Везде впихивают ИИ, который никто не просил: браузеры, ОС, конференц-приложения ломаются, но деньги текут в «искусственный интеллект».
Gamescom добавил ИИ-расписание: люди получили сотни ненужных встреч, функцию быстро убрали.
Те же деньги могли бы починить DM, поиск, перенос встреч — базовые вещи, из-за которых все возвращаются к почте и LinkedIn.

Мотив один: быстрая прибыль. В итоге продукты гниют, а инвесторы кормят обещания «вот-вот будет AGI».
Один бюджет крупной компании хватило бы на 100 лет развития Godot, Blender, Ladybird — реальных инструментов, которые нужны сегодня.

Потерянные годы не вернуть.

• Участники жалуются, что вместо починки старых багов и улучшения базовых функций компании впихивают «AI-фичи», которые никому не нужны.
• Многие считают, что инвесторы сознательно выбирают технологии, которые трудно децентрализовать, чтобы сохранить контроль и монополию.
• Одни видят в нынешнем AI-хайпе очередную моду, как было с UML, блокчейном и облаками; другие – шанс на прорыв, оправдывающий «пузырь».
• Популярная идея: деньги лучше бы пошли на документацию, API и совместимость, а не на обучение моделей водить мышкой по браузеру.
• Подводный тезис – проблема не в AI, а в концентрации капитала и в том, что «зелёное поле» проще финансировать, чем ремонт «коричневого».

• Чёткое ТЗ — пишу заранее, чтобы агент видел контекст.
• Файл-инструкция по запуску линтервов и сборки.
• Саморевью — прошу Claude проверить свой код.
• Глобальный гайд ~/.claude/CLAUDE.md с правилами: мелкие шаги, TDD, простые решения, максимум 3 попытки при ошибке.

Качество
Я вручную читаю и тестирую всё, что выходит из LLM; отвечаю за PR независимо от автора кода.

• Ключ к успеху — писать подробные спецификации: кто-то тратит 2 часа на 12-шаговый документ и получает отличный результат, другие же считают, что даже «чистые» спеки не спасают от схода с курса и бесконечных правок.
• Мнения о CLAUDE.md разделились: одни держат файл коротким (<100 строк) и минималистичным, другие вообще не видят в нём пользы из-за «context rot» и субъективных инструкций.
• Работа с большими старыми кодовыми базами по-прежнему сложна: большинство признаёт, что Claude Code лучше справляется с новыми pet-project’ами, чем с «грязными» legacy-фичами.
• Популярные тактики: шаг-за-шагом микро-PR, TDD-агент, запуск puppeteer-тестов для «замыкания цикла», code-review собственных патчей самим агентом.
• Некоторые вообще отказались от спецификаций: инкрементально подсказывают «следующий шаг, какой сделал бы я», сразу коммитят дифф и правят на лету.