https://valoryx.org/ru/blog/ Recent content in Блог on Valoryx Hugo ru Mon, 13 Apr 2026 00:00:00 +0000 https://valoryx.org/ru/blog/ai-native-documentation/ Mon, 13 Apr 2026 00:00:00 +0000 https://valoryx.org/ru/blog/ai-native-documentation/ У документации проблема с обслуживанием. Вы пишете руководство, публикуете его, и через три месяца оно устарело. API изменился. Формат конфигурации переработан. Зависимость заменена. На скриншотах интерфейс, которого больше не существует. Решение не в том, чтобы «писать лучшую документацию» или «строить культуру документации». Команды пытаются это делать десятилетиями. Решение в том, чтобы документация знала о коде, который описывает, — чтобы при изменении кода документация об этом узнавала. Вот что означает ИИ-нативная документация. https://valoryx.org/ru/blog/documentation-platform-cost/ Thu, 09 Apr 2026 00:00:00 +0000 https://valoryx.org/ru/blog/documentation-platform-cost/ Поюзерное ценообразование выглядит разумно на первый взгляд. Пять пользователей по $8/мес? Это $40. Ваша команда может позволить $40. Но документация — это один из тех инструментов, где число людей, которые должны иметь доступ, постоянно растёт. Инженерам нужно писать. Продакт-менеджерам нужно проверять. Поддержке нужно ссылаться. Новым сотрудникам нужно читать и комментировать. Внезапно у вас не 5 мест — а 50, и эти «доступные» $8/место превращаются в $400/мес за инструмент, который хранит текстовые файлы. https://valoryx.org/ru/blog/docs-for-open-source/ Mon, 06 Apr 2026 00:00:00 +0000 https://valoryx.org/ru/blog/docs-for-open-source/ Проекты с открытым исходным кодом живут или умирают благодаря документации. Библиотека с хорошей документацией находит пользователей. Библиотека с голым README и подходом «смотрите код» форкается тем, кто напишет лучшую документацию — или просто игнорируется. Но большинство инструментов документации создано для компаний, а не для мейнтейнеров OSS. Они берут плату за пользователя, за страницу или за workspace. Для проекта, поддерживаемого волонтёрами с нулевым бюджетом, это неприемлемо. Мы создали Community Edition DocPlatform бесплатным навсегда, без ограничений. https://valoryx.org/ru/blog/documentation-search-works/ Thu, 02 Apr 2026 00:00:00 +0000 https://valoryx.org/ru/blog/documentation-search-works/ Вы вводите запрос в строку поиска документации. Появляются результаты. Но что произошло между нажатием клавиши и результатами? Для большинства платформ документации ответ — либо «немного» (простое сопоставление ключевых слов, которое пропускает очевидные результаты), либо «много инфраструктуры» (кластер Elasticsearch, который ваша команда эксплуатации должна поддерживать). Есть золотая середина, о которой большинство команд не знают: встроенный полнотекстовый поиск. DocPlatform использует Bleve, поисковую библиотеку на Go, скомпилированную прямо в бинарный файл. Никаких внешних сервисов, сетевых вызовов, кластеров для управления — но с функциями, которые вам реально нужны: стемминг, нечёткий поиск, бустинг полей и ранжирование по релевантности. https://valoryx.org/ru/blog/single-binary-architecture/ Mon, 30 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/single-binary-architecture/ Большинство платформ документации поставляются как стек. Вы получаете Node.js-приложение, базу данных PostgreSQL, кэш Redis, кластер Elasticsearch для поиска и обратный прокси Nginx, чтобы связать всё вместе. Пять сервисов, пять вещей, которые могут сломаться, пять вещей для мониторинга, обновления и патчинга. DocPlatform поставляется как один файл. Скачайте, запустите, готово. Это не маркетинговый трюк. Это архитектурное решение, принятое в первый день, и каждый последующий выбор проектирования вытекает из него. Вот почему. Типичный стек документации Давайте посмотрим, что вы реально развёртываете при настройке современной платформы документации: https://valoryx.org/ru/blog/keep-docs-up-to-date/ Thu, 26 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/keep-docs-up-to-date/ У каждой инженерной команды одна и та же проблема с документацией. Кто-то пишет подробную документацию при запуске. Через полгода API изменился, формат конфигурации другой, а три страницы ссылаются на функцию, которую переименовали. Никто не обновил документацию, потому что обновление документации — это отдельная задача от написания кода, а отдельные задачи забываются. Обычный совет — «сделайте документацию частью культуры» — не работает. Культура не выдерживает давления дедлайнов. Работает то, что делает обновление документации частью существующих рабочих процессов, чтобы оно происходило автоматически или с минимальным трением. https://valoryx.org/ru/blog/docs-regulated-industries/ Mon, 23 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/docs-regulated-industries/ Если вы работаете в здравоохранении, оборонной промышленности, финансах или любой отрасли, где важна резидентность данных, у вас наверняка уже был такой разговор: «Можно ли нам использовать этот SaaS-инструмент, или нужно пройти шестимесячную проверку безопасности?» Для большинства облачных платформ документации ответ — проверка, и часто она заканчивается словом «нет». Проблема не в том, что облачные инструменты небезопасны. Большинство из них компетентны в вопросах безопасности. Проблема в контроле. Регулируемые среды должны доказать, где находятся данные, кто имеет к ним доступ, как они зашифрованы и что происходит при инциденте. https://valoryx.org/ru/blog/bidirectional-git-sync/ Thu, 19 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/bidirectional-git-sync/ Каждая платформа документации со страницей интеграции с git даёт одно и то же обещание: ваша документация живёт в git, команда редактирует в браузере, и всё остаётся синхронизированным. На практике большинство этих интеграций — односторонние зеркала, которые разваливаются, как только два человека вносят правки с разных сторон. Мы написали о том, почему это происходит, в предыдущей статье. Эта идёт глубже в решение: как Valoryx реализует двунаправленную синхронизацию с использованием паттерна Content Ledger и почему этот подход справляется со сценариями, которые ломают другие инструменты. https://valoryx.org/ru/blog/mcp-documentation-guide/ Mon, 16 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/mcp-documentation-guide/ Model Context Protocol (MCP) — это открытый стандарт, позволяющий ИИ-ассистентам взаимодействовать с внешними инструментами и источниками данных через структурированный интерфейс. Вместо копирования текста в окно чата в надежде, что модель поймёт контекст, MCP даёт ассистенту прямой типизированный доступ к вашим системам — чтение файлов, выполнение поиска, создание контента — всё через чётко определённые вызовы инструментов. Для команд, работающих с документацией, это фундаментально меняет рабочий процесс. Ваш ИИ-ассистент перестаёт быть генератором текста, работающим из устаревшего контекста, и становится участником, который читает реальную документацию, ищет по всей базе знаний и вносит правки, которые вы можете проверить перед публикацией. https://valoryx.org/ru/blog/internal-docs-developers-use/ Thu, 12 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/internal-docs-developers-use/ В каждой инженерной организации есть внутренняя документация. И в большинстве из них эта документация неполна, устарела или игнорируется. Согласно опросу разработчиков Stack Overflow 2024, большинство разработчиков считают плохую или отсутствующую документацию серьёзным барьером для продуктивности. Это не проблема дисциплины. Это проблема инструментов. Внутренняя документация терпит неудачу по конкретным, устранимым причинам. Инструменты делают написание болезненным. Контент устаревает, потому что ни у кого нет рабочего процесса для поддержания актуальности. Поиск плохо работает, поэтому разработчики идут сразу в Slack. https://valoryx.org/ru/blog/docs-should-be-in-git/ Mon, 09 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/docs-should-be-in-git/ Вот список того, что типичная инженерная команда хранит в git: Исходный код приложения Описания инфраструктуры (Terraform, Pulumi, CloudFormation) Конфигурации CI/CD-пайплайнов Скрипты миграции базы данных Спецификации API (OpenAPI, protobuf) Манифесты развёртывания (Kubernetes, Docker Compose) Шаблоны конфигурации окружения А вот что обычно живёт вне git: Документация Это странно. Документация описывает систему. Она меняется, когда меняется система. Она нуждается в ревью, версионировании, атрибуции и возможности отката. Каждый другой артефакт с этими свойствами живёт в git. https://valoryx.org/ru/blog/documentation-as-code/ Thu, 05 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/documentation-as-code/ «Документация как код» — выражение, которое звучит повсюду. В самом простом виде это означает обращение с документацией так же, как с исходным кодом: хранение в системе контроля версий, написание в виде простого текста, ревью через pull request, сборка через CI/CD. Но между идеей и её качественной реализацией есть разрыв. Это руководство описывает, что такое docs-as-code, какие подходы существуют и в чём каждый из них уступает. Почему docs-as-code важен У программных команд уже есть рабочие процессы для управления изменениями. https://valoryx.org/ru/blog/self-host-docs-5-minutes/ Mon, 02 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/self-host-docs-5-minutes/ Большинство инструментов для самостоятельного хостинга документации требуют базу данных, обратный прокси и полдня правки YAML, прежде чем вы увидите экран приветствия. DocPlatform — это один бинарный файл на Go без внешних зависимостей. Это руководство проведёт вас от нуля до опубликованной документации примерно за пять минут. Требования Вам нужен компьютер с Linux, macOS или Windows. Всё. Без Docker, без PostgreSQL, без Node.js. DocPlatform компилируется в один статический бинарный файл — среда Go встроена. https://valoryx.org/ru/blog/notion-alternative-self-hosted/ Sun, 01 Mar 2026 00:00:00 +0000 https://valoryx.org/ru/blog/notion-alternative-self-hosted/ Notion есть везде. Команды разработчиков всё активнее используют его для технической документации. Он работает — до определённого момента. Что Notion делает правильно Быстрый и гибкий редактор. Полезные представления баз данных. Хорош для нетехнической документации. Где Notion даёт сбой Нет интеграции с git. Документация хранится в проприетарной базе данных Notion, оторванной от кодовой базы. Расхождение документации с кодом практически неизбежно. Привязка к платформе. Экспорт в markdown неаккуратен. Проприетарные блоки становятся неопределёнными. Ваша документация — в заложниках. https://valoryx.org/ru/blog/self-hosted-docs-guide/ Fri, 27 Feb 2026 00:00:00 +0000 https://valoryx.org/ru/blog/self-hosted-docs-guide/ Self-hosted документация переживает подъём. После многих лет, когда SaaS-платформы повышали цены, меняли условия использования и закрывались без предупреждения, всё больше команд выбирают собственную инфраструктуру для хранения документации. Причины очевидны: владение данными, контроль затрат, соответствие нормативным требованиям и уверенность в том, что база знаний не исчезнет, когда у стартапа закончится финансирование. Однако рынок self-hosted документации перенасыщен и запутан. Существуют wiki-платформы, генераторы статических сайтов, базы знаний и гибридные инструменты — каждый со своими компромиссами. https://valoryx.org/ru/blog/gitbook-vs-valoryx/ Wed, 25 Feb 2026 00:00:00 +0000 https://valoryx.org/ru/blog/gitbook-vs-valoryx/ GitBook — одна из самых популярных платформ документации для команд разработчиков. Мы создали Valoryx, чтобы решить проблемы, которые GitBook не решает: владение git-репозиторием, self-hosting и прозрачность ценообразования. Опыт работы с редактором GitBook: отличный блочный редактор, зрелые инструменты совместной работы. Valoryx: WYSIWYG на базе Tiptap, более быстрый, чистый markdown. Вердикт: GitBook зрелее; Valoryx быстрее и генерирует более чистый markdown. Интеграция с git «Git Sync» в GitBook не является по-настоящему двусторонним — push из IDE вызывает конфликты слияния. https://valoryx.org/ru/blog/why-git-sync-breaks/ Sun, 22 Feb 2026 00:00:00 +0000 https://valoryx.org/ru/blog/why-git-sync-breaks/ Вы подключаете репозиторий, делаете push из IDE — и получаете конфликты слияния. Потерянные правки. Молчаливые откаты. Это фундаментальный архитектурный изъян. Три способа сломать git sync 1. Одностороннее зеркалирование. Большинство платформ используют git как резервную копию. Push из IDE вызывает конфликты. 2. Приоритет базы данных над git. Wiki.js: база данных — источник истины. Git — экспорт только для чтения. Нельзя сделать git clone, push и увидеть результат в интерфейсе. 3. Деструктивное разрешение конфликтов.