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

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

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

Для описания архитектуры важно выбрать подход, который будет понятен всей команде. Одним из них является нотация C4, разработанная Саймоном Брауном.

Данная статья — это продолжение и значительное дополнение моей предыдущей статьи по C4, опубликованной в 2023 году. Здесь я детально разобрала для вас каждый уровень и элемент нотации, распространённые ошибки и спорные вопросы, а также инструменты для создания диаграмм, в частности графический редактор Draw.io и Structurizr для создания C4 через код.

Внутри — много схем, картинок и практических примеров для монолитной и микросервисной архитектуры, готовый код Structurizr и промпт для ИИ. Статья организована таким образом, чтобы вы могли открыть её, последовательно пройти все разделы и самостоятельно разобраться с C4.

Статья будет полезна системным и бизнес-аналитикам, архитекторам, разработчикам, менеджерам проектов и всем, кто участвует в проектировании архитектуры систем.

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

В эпоху 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. В конце статьи вас ждет небольшой бонус в виде шаблона с настроенными стилями форматирования.