Подготовка технической документации *

В эпоху AI код становится дешевле, а качественное инженерное решение — ценнее.

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

Viaduct помогает превратить архитектурное проектирование в структурированный, проверяемый и доступный AI-агентам контекст — от модели системы до Change Set, по которому можно безопасно реализовать изменение.

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

Но с другой стороны — RAG-пайплайн тяжёлый и трудозатратный. Компания хочет чат по своей документации. Разработчик говорит: нужен пайплайн — чанкинг, эмбеддинги, векторная база, реранкер. Два-три месяца работы плюс сервис, который надо вечно поддерживать, ради 400-страничной документации. И всё это занимает месяцы, тратит ресурсы ради не такой уж и большой выгоды.

Сегодня многие модели держат 1M токенов, а то и больше, а в это окно контекста чаще всего спокойно влезает вся документация. Но если не влезет — то обязательно ли сразу строить весь RAG самому? А как понять, когда есть альтернатива RAG, а когда нет?

В этой статье мы разберём, почему RAG стал выбором по умолчанию (и почему это было оправдано), посмотрим, как падает качество при Long Context, сравним подходы и узнаем, что, как и когда использовать.

Я, как технический писатель-аналитик, каждый день делегирую искусственному интеллекту создание текстов, структурирование и генерацию документации. Но иногда модель выдаёт такие глупые логические ошибки, что хочется ̶н̶а̶о̶р̶а̶т̶ь̶ ̶н̶а̶ ̶н̶е̶е̶ ̶ закрыть чат и переписать всё руками.

Благодаря трёхнедельному отпуску удалось наконец поизучать фундаментальное устройство нейросетей с точки зрения когнитивных наук, чтобы разобраться, как же им удается писать крутые тексты за считанные секунды.

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

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

Перевод по СБП — это не одна стрелка между двумя сервисами, а лимиты, антифрод, идемпотентность, НСПК, Kafka и уведомления. Я попробовал собрать этот сценарий не на вайтборде, а в виде интерактивного потока — и сразу нашел несколько дыр в архитектуре.

Требование может выглядеть понятным на этапе обсуждения, но при передаче в разработку превратиться в источник вопросов и переделок. В статье разберём, как находить «смысловую кашицу» в требованиях: выявлять скрытые допущения, пропущенные сценарии и слабые места ещё до начала реализации.

Вы когда-нибудь подписывали положение о неразглашении коммерческой тайны или положение об информационной безопасности? Наверняка ответ будет положительный. Всё это верхняя часть айсберга, который называется «Регламентирующие документы» (РД). К видам таких документов относятся положения, кодексы, должностные инструкции, приказы по компании, штатное расписание.

Чем сложнее бизнес-процессы и чем сильнее формализована сфера деятельности компании, тем больше таких документов. Мы чтим законодательство, а совокупность внутренних нормативных документов (их еще называют «локально-нормативные акты», «локальные нормативные документы» или «внутренние нормативные документы») — это правовые акты «в миниатюре» и от того, как эффективно выстроена эта база зависит то, насколько хорошо работает организация в целом.

Почему выиграть тендер ещё не значит заработать, чем реально отличаются 44-ФЗ и 223-ФЗ, сколько денег нужно на обеспечение и старт, почему низкая цена побеждает не всегда и где в госзакупках уже работает ИИ? Госзакупки для многих предпринимателей до сих пор выглядят как территория с предупреждающими знаками: десятки страниц документации, электронные площадки, обеспечения, ФАС, РНП и устойчивое убеждение, что «там всё уже поделено». При этом для тысяч компаний тендеры — обычный канал продаж, через который можно получить клиента на миллионы рублей без классической рекламы и холодного отдела продаж.

Я, Александр, автор телеграм-канала «Shulepov Code», поговорил с Тураном Амировым — предпринимателем и экспертом по тендерам, автором YouTube-канала «TURAN TENDER» который пришёл в закупки из грузоперевозок, прошёл путь от первых заявок практически вслепую до крупных контрактов, ошибок, конфликтов с заказчиками и внедрения тендерных процессов в других компаниях. В этом интервью мы разбираем, чем отличаются 44-ФЗ и 223-ФЗ, сколько денег действительно нужно для старта, почему низкая цена побеждает не всегда, зачем предпринимателю самому понимать ТЗ и где в этой системе сегодня можно использовать ИИ. Туран делится реальным опытом работы с госзакупками, кейсами и объясняет, как устроен рынок без мифов.  

Всем привет! Меня зовут Евгения Красильникова, я технический писатель в команде Russtech (разработчики IT-решений ведущего российского оператора рекламы вне дома Russ, входит в RWB). Сегодня я хочу рассказать, как мы пришли к единой системе оценки задач и с помощью нейросети создали удобной инструмент, который помог ввести подсчет наших трудозатрат и заметно оптимизировал рабочие процессы.

Человек готовит договор для внешней стороны, закрашивает в нём чёрным прямоугольником номер счёта, сохраняет в PDF, отправляет. Прямоугольник на месте, ничего не видно, всё в порядке.

Номер счёта при этом уезжает вместе с файлом. Целиком, в открытом виде — его достаёт любой инструмент, умеющий вытаскивать текст, и даже обычное выделение мышью в просмотрщике.

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

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

Меня зовут Лена, я технический писатель в VAS Experts. В компании документация хранится в DokuWiki и размещена на двух площадках. В этой статье расскажем, почему для этой задачи мы выбрали именно платформу DokuWiki и какие собственные инструменты добавили поверх стандартных возможностей.

Как описывать не только сервисы и связи, но и реальные бизнес-сценарии внутри распределённой системы? Показываю Magic Flows в Viaduct: пошаговые потоки данных, визуальный плеер на C4-модели, автоматическая sequence diagram и документация, привязанная к конкретному процессу.

Салют, Хабр!

Я Антон, продакт сервисов клиентской документации. Одна из задач нашей команды — решать проблемы пользователя как можно проще: без долгих диалогов с чат-ботом или техподдержкой, где приходится излагать, что случилось, как и когда; без поисковиков в надежде, что где-то на форумах найдётся ответ. Поэтому мы запустили на интеллектуальных телевизорах и медиацентрах Сбер сервис персонализированной контекстной помощи — ГигаСправку. Теперь, если устройство выдаёт ошибку, вместе с ней на экране появляется кнопка ГигаСправки. Нажав на неё, пользователь получает совет, как можно исправить проблему с учётом конкретного устройства и его состояния.

Эффект от нового сервиса для техподдержки огромен, а техническая реализация проста: всего одна точка знаний, RAG-сервис, ГигаЧат и семантическое кэширование позволяют предельно быстро помогать юзеру на той же поверхности. Показывать то, что нужно, там, где нужно. Рассказываем, как превратили базу с ответами на вопросы в ГигаСправку.

Привет, Хабр! На связи старший технический писатель РТЛабс Фёдор Пеплин.

Команда РТЛабс — коллектив из 2500+ человек. Объём контента для такого количества сотрудников может исчисляться миллионами знаков, а количество пространств, используемых для хранения информации и работы с ней, — несколькими сотнями. При этом всем нам нужно хранить информацию и обмениваться ею. Один из инструментов, который мы используем для этого, — Atlassian Confluence. В этой статье я поделюсь некоторыми лайфхаками, которые позволят значительно упростить работу с ним.

У каждого опубликованного сайта GitBook уже есть MCP-сервер. Мы узнали об этом случайно и вместо конвертеров просто дали агенту ходить в документацию напрямую — сотня страниц переехала на Diplodoc за четыре дня. Что агент сделал сам, где проходит граница его возможностей и какие десять вещей пришлось доделывать руками.

Срочно нужно поправить отчет, который руководитель требовал ещё вчера. И вот вы вставляете последнюю таблицу в документ и… нумерация поехала, таблица «ушла на перекур». Знакомая ситуация? Тогда я как технический писатель в ЛАНИТ с многолетним опытом хочу поделиться несколькими приемами владения Word, которые систематизируют хаос работы с документами и помогут перестать его ненавидеть.

P. S. В конце статьи вас ждет небольшой бонус в виде шаблона с настроенными стилями форматирования. 

Предисловие

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

Сразу оговорюсь, что это не enterprise решения.

Это небольшие мобильные приложения, разрабатываемые в режиме вайб-кодинга с использованием ИИ-агента Claude Code Opus 5

Концепция приложения

App Concept

Краткое описание приложения.

Очень краткое, на языке пользователя, без технических подробностей.

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

Часто формулируется как ответ на вопрос - “Чего хочет пользователь?”

Хранится в архиве проекта.

Как правило, не редактируется.

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

Чтобы обновить одно видео, надо открыть OBS, поднять чистый профиль браузера — иначе в кадр лезут закладки и всплывашки. Потом записать дубль, в котором ты ни разу не промахнулся мышкой. Потом порезать в редакторе, наложить подписи. На семь видео уходит день. Через два месяца — опять день.

Предсказуемо, видео перестали обновлять. Тогда я написал штуку, которая собирает ролик из текстового файла.

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

В этой статье разберём, что такое Tg, почему он важен и как правильно выбрать материал под конкретную задачу.