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

Около 90% фронтенд‑разработчиков в нашей команде используют ИИ‑помощников для написания кода. Лично у меня — и как я могу заметить, у многих — был такой опыт: вы только начинаете пользоваться ИИ‑помощником, просите его сгенерировать какое‑нибудь классное MVP, получаете результат минут за пять и думаете: «Вау, неужели это возможно? Как это вообще работает и как это круто». 

А дальше вас ждёт сюрприз. 

Всем привет, меня зовут Валерий Баранов, я руковожу командой технологий фронтенда в Яндекс 360. Мы занимаемся тем, что сами называем «общим фронтендом»: общими техническими компонентами, общим CI/CD, платформами дистрибуции общих компонентов. Сегодня я хочу рассказать, как мы в Яндекс 360 сделали фронтенд‑проекты по‑настоящему AI‑ready: научили ассистентов понимать структуру наших репозиториев, работать с внутренними библиотеками и даже соблюдать паттерны дизайн‑системы. 

Привет, хабр! Решил поделиться с миром своим проектом, который делался в свободное время и был мне полезен на моей текущей работе. Ссылка на гитхаб https://github.com/simplepersonru/SimpleOntoDoc

Проект - генератор статического сайта документации для онтологической модели данных
Онтологическая модель данных — это способ формального описания предметной области, в основе которого лежат три главные вещи:

1. Классы (типы объектов, «сущности»).
2. Атрибуты (свойства этих классов).
3. Связи (отношения между классами).

Под катом:

+ Мотивация (зачем мне это нужно)
+ Как это выглядит (с опубликованным примером)
+ Как можно применить (зачем Вам это нужно)

AI дисклеймер - при написании статьи активно использовалась нейросеть головного мозга, будьте осторожны

Лавинообразный рост информации превратил привычный Ctrl+F в артефакт прошлого. Мы открываем тяжёлые PDF-файлы, зарываемся в десятки вкладок, пытаясь выудить одну нужную строчку, и тратим на это часы, которых и так вечно не хватает.

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

В этом обзоре мы собрали самых интересных игроков на этом поле:
• BotHub,
• Brave Search,
• ChatPDF,
• “ГигаЧат”,
• Felo AI,
• iAsk,
• Komo,
• Perplexity
• и DuckDuckGo –

Всё, чтобы вы могли выбрать идеальный инструмент для своей задачи – будь то быстрый ответ или глубокое исследование. Готовьте свои самые сложные документы и вопросы – сейчас будем разбираться, кто из них действительно умеет искать иголку в стоге сена. Узнайте, как превратить хаос информации в стройную систему с помощью ИИ.

Документацию можно готовить где угодно и как угодно. Писать инструкции в многочисленных CCMS, публиковать сайты через генераторы наподобие Sphinx, применять сложные разметки вроде DITA, вести базы знаний в Confluence или вообще собирать файлы в Word. У каждого инструмента и подхода есть свои плюсы и минусы. Выбор зависит от множества факторов: сложности, требований к результату, потребителя контента, бюджета отдела, объема накопившегося легаси — да и просто моды в профессиональной среде.

Но что если посмотреть на вопрос с другой стороны? Что если выбирать и проектировать систему документирования исходя из того, сколько свободы предоставляется техническому писателю?

Давайте выкрутим регулятор свободы на максималку сначала в одну сторону, когда техпис не имеет абсолютно никаких рамок и ограничений, а затем в противоположную, когда он тотально несвободен. Какие преимущества будут у каждой из этих двух крайностей и какие выводы можно будет сделать по итогу такого мысленного эксперимента — об этом моя статья.

Когда вы последний раз читали документацию размером более страницы А4 без привлечения LLM? Вопрос риторический.

Кажется пришло время вычеркнуть написание документации из списка тех. долга.

В статье я попытался переосмыслить саму идею документации для enterprise разработки, а также рассказать о практическом решении поднятого вопроса для любой системы на платформе 1С 8.3 и выше. 

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

Напомним, что функциональные требования – это не 50% от общего объема всех требований к Системе, которые определяют 100+ % успеха разработки и реализации.

Итак, что точно не нужно делать.

Я перепробовал несколько способов вести документацию по базе данных — и у каждого были свои проблемы: информации недостаточно, сложно поддерживать, непонятна команде. Хуже всего, что плохая документация по БД тянет за собой проблемы с требованиями к данным — а это не только таблицы, но и миграции, и данные в коде. В какой-то момент я понял, что пытался решить одним документом три разные задачи.

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

Неизменно было только одно – основную ценность представляет код. Код – это истина в последней инстанции. Требования, архитектура, тест-кейсы — не более чем черновики, наброски, которые могут быть уничтожены сразу после начала «настоящей работы» – написания кода.

Но что, если я скажу, что сейчас происходит тихая контрреволюция? Индустрия устала от неопределенности. Когда код — единственная истина, система превращается в «черный ящик». Понять, как она работает фактически, можно только прочитав тысячи строк кода.

Код идеально отвечает на вопрос «как?», но в нем нет ответа на вопросы «зачем?», «для кого?», «почему?».  Без знания ответов на эти вопросы, любая доработка —  это гадание на кофейной гуще.

В этой статье проследим эволюцию: от Водопада к Agile, от Agile к Гибридам и Everything as Code.

Привет, Хабр! Сегодня хотелось бы поднять актуальную тему – перевод технической документации и то, как стандартизированный английский язык может существенно упростить этот процесс.

Техническая документация чаще всего пишется на английском языке. Документацию используют международные команды и на ее основе создаются переводы и обновляются новые версии инструкций.

Со временем документация растет, ее пишут разные авторы, формулировки начинают отличаться, а терминология используется не всегда последовательно. Это делает английские тексты менее однозначными, усложняет перевод и снижает эффективность систем памяти перевода (translation memory). 

С подобной задачей к нам обратились несколько клиентов, работающих с большими объемами технической документации. Чтобы стандартизировать тексты и упростить их перевод, мы начали применять подход Simplified Technical English (STE) – контролируемый вариант английского языка для технической документации. В этой статье разберем, что такое STE и как он помогает стандартизировать документацию и улучшить  машинный перевод. 

Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для ИТ-команд.

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

Один из примеров такой документации — Architecture Decision Records — короткие структурированные документы, которые фиксируют одно конкретное архитектурное решение вместе с контекстом, рассмотренными альтернативами и принятыми trade-off'ами. Ключевое слово — конкретное. ADR — это не архитектурный обзор системы и не проектная документация. Это ответ на один вопрос: «почему мы решили именно так, а не иначе?»

На эту статью меня вдохновил испанский ИИ-слоп и тред на Hacker News вокруг вопроса «как вы фиксируете ПОЧЕМУ инженерных решений, а не только ЧТО?». В статье напомню, зачем нужен ADR и какие есть стандартные проблемы. Также приведу выжимки из кейсов, в которых описаны любопытные ИИ-автоматизации.

Всем привет. Меня зовут Никита, я руковожу командой Цикл‑ОН. Мы уже более 5 лет ведем проекты по заказной разработке ПО и, как и многие, сталкиваемся с необходимостью разработки не только качественного кода, но и документацию на продукты. В нашей нише особенность, что заказчики живут в парадигме ГОСТа. Я бы здесь хотел оставить небольшую заметку о нашем опыте — как то, что для начаиналось как откровенное мучение превратилось сначала в умную идеологию, а по итогу в самостоятельное решение для подготовки документации.

Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для ИТ-команд.

В Gramax мы делаем упор на качественную работу как человека, так и машины. И часто получаем вопросы, как автор статей может повлиять на качество выдачи ИИ-поиска.

В большей мере качество поиска зависит от нас: мы регулярно улучшаем внутренние механизмы, чтобы авторы не становились заложниками технологий. Но есть универсальные правила, которые работают в любой системе с RAG. Этими правилами и хотим поделиться в этой статье:)

Стремительное развитие ИИ в последние годы привело к невиданному росту популярности Markdown. Почти все современные LLM — от ChatGPT до Claude — по умолчанию выдают ответы в этом формате. Мы привыкли оформлять в нем заметки в Obsidian, писать промпты, вести документацию в GitHub и общаться в рабочих мессенджерах. Markdown стал «лингва-франка» современного интернета.

Но есть одна проблема. Использовать Markdown с русским языком — это боль.

Вам нужно поставить заголовок? Alt+Shift -> # -> Alt+Shift обратно. Нужно выделить код? Снова чечётка по клавишам переключения раскладки. Стандартная русская раскладка в Windows будто застряла в прошлом веке. Клавиша Shift+3 выдает нам символ №, который в 2024 году нужен крайне редко, в то время как жизненно необходимые решетки, собаки и скобки заставляют нас постоянно прыгать между языками.

Я решил эту проблему для Windows с помощью небольшого скрипта на AutoHotkey (v2).

Привет, Хабр! Меня зовут Руслан Назаров, я директор по разработке TATLIN.FLEX в YADRO. Недавно я начал возрождать культуру составления спецификаций, и она уже дает первые плоды. Мы с командой выстроили процесс работы, подобрали оптимальных участников, составили шаблоны и проверили их в работе. В этом материале расскажу, с чего начать, если в вашей компании спеки еще не написаны, и поделюсь шаблоном — его можно скачать по ссылке в конце статьи.

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

В статье разберем подход Documentation as Code, почему OpenAPI давно показал его ценность и как развитие ИИ делает структурированную документацию практически обязательной.

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

Привет, Хабр! На связи QA-команда мобильных секретарей — Настя и Ксюша.

Как и многие в QA, мы постоянно работаем с документацией. Ее много, она лежит в Confluence, постоянно меняется, что-то прилетает от партнеров, что-то дописывают аналитики и разработчики. 

В итоге на то, чтобы собрать все воедино, проанализировать и написать качественные чек-листы или тест-кейсы, уходит много времени. В какой-то момент мы подумали: «А что, если создать AI-агента, заточенного под наши процессы, который будет делать это за нас?». Так и родился наш проект.

Рассказываем, как это было.

Разрабатываю AI-агента персональной аналитики для себя вместе с Claude Code. Любопытной инженерной задачей оказалась архитектура памяти. Как сделать, чтобы агент помнил не только последний разговор, но и паттерны, накопленные за месяцы? В этой статье описана архитектура, рабочие решения и грабли, на которые я наступила.

Если вы ещё не создавали сервис с помощью ИИ, честно, я вам завидую. Вспоминаю то чувство, которое испытывал летом 2025-го, когда начал экспериментировать с этим.

Если вы уже прочитали Часть 1 и Часть 2, то сейчас вы находитесь в одном из самых захватывающих моментов всего процесса.

И мой совет может показаться странным: остановитесь на несколько дней на этапе формирования самого первого промпта для Курсора или подобной платформы.

Это перевод статьи с opensource.com, которая мне показалась особенно полезной и практичной, поэтому решил поделиться адаптированной версией для русскоязычной аудитории. Оригинал доступен по ссылке: https://opensource.com/article/22/10/docs-as-code

В статье разбирается подход Docs as Code — способ встроить документацию в процесс разработки так, чтобы она проходила через Git, ревью и автоматическую сборку вместе с кодом. Материал будет полезен разработчикам, тимлидам и тем, кто выстраивает инженерные процессы в команде.