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

Привет, Хабр! Меня зовут Руслан Назаров, я директор по разработке 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, ревью и автоматическую сборку вместе с кодом. Материал будет полезен разработчикам, тимлидам и тем, кто выстраивает инженерные процессы в команде.

Помните момент, когда вы впервые попробовали ChatGPT или GitHub Copilot? У меня это было похоже на взрыв: привычные процессы рухнули, а на их месте начала формироваться новая реальность. ИИ не просто ускоряет работу — он заставляет переосмыслить сам подход к хранению и обработке информации.

Раньше я, как и многие, хранил готовые документы: Word‑отчёты, PowerPoint‑презентации, схемы в графических редакторах. Потом пришёл момент, когда я поймал себя на мысли:

«Почему я трачу время на поддержание десятков копий одного и того же текста? Почему не хранить „исходники“, а документы генерировать по мере необходимости — как сборку кода?»

Так родилась концепция, о которой я хочу рассказать.

Всем привет! Я Елена Шустерман, ведущий технический писатель в РТЛабс.

Это вторая часть статьи «Давайте сократим сокращения». Расскажу ещё немного про редактор MS Word и поиске с подстановочными знаками — об использовании фильтра с подстановочными знаками для усложненной задачи.

Пользовательское требование описывает, что нужно пользователю. Критерии приёмки — фиксируют, как это проверить. Но между «что нужно» и задачей в Jira — пропасть. Чтобы её закрыть, я пишу функциональные требования — с use case'ами, из которых тестировщик может собрать тест-кейсы, а разработчик — понять ожидаемое поведение системы.

Без хорошо проработанного и грамотно оформленного требования невозможно создать качественный IT-продукт. На что стоит обратить внимание бизнес-аналитику при подготовке требований? В этой статье в блоге ЛАНИТ я попробую подсветить эти моменты. При этом вопросы сбора и приоритизации я решил не рассматривать: будем считать, что все требования собраны.

Аннотация

С 2026 года строительная отрасль России столкнется с массовыми изменениями в оформлении проектной, рабочей и инженерной документации: введены новый национальный стандарт ГОСТ Р 21.101-2026, охватывающий строительство, реконструкцию, капремонт, эксплуатацию и ликвидацию зданий, а также отчетную техническую документацию и результаты изысканий. В параллельном процессе ужесточаются требования к формату заверения документов с переходом к полной цифровизации. С 1 марта 2026 года вступают в силу изменения в Градостроительный кодекс РФ, обязывающие использование усиленной квалифицированной электронной подписи (УКЭП) для проектной документации; использование информационно-удостоверяющих листов (ИУЛ) как альтернативы УКЭП запрещено.

Для реализации требований Минстроя о повсеместной подписи документов необходима связка отечественного ПО: КриптоПро CSP (криптопровайдер) и КриптоАРМ (графический интерфейс). В КриптоАРМ создается файл подписи, в который поочередно добавляются подписи всех участников проекта в едином файле (.sig/.p7s) через процесс соподписания. Этот подход обеспечивает соответствие новым требованиям к цифровой подписи и экспертизе документации. Также в статье рассматривается вариант использования сервиса КриптоАРМ Документы, который позволяет управлять очередностью подписей и устранить различные риски пересылки фрагментов документации по почте.

Разработка любого ИТ-продукта, если она ведётся осознанно и целенаправленно, а не спонтанно и хаотически, требует чёткой постановки задачи – что должно быть получено в результате. Соответственно, необходимо описание требований к создаваемому продукту, которое и принято называть «ТЗ» – Техническим заданием.

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

Однако, возникает логичный вопрос – ДЛЯ КОГО должно быть написано ТЗ.

Из этого уже вытечет следующий вопрос – ЧТО должно быть включено в ТЗ, т.е. какие требования составляют спецификацию (как, собственно, в иностранных языках ТЗ обычно и называется – «спецификация требований»).

Конечно, можно (и, в большинстве случаев, нужно) использовать существующие стандарты – например, отечественные ГОСТ 19.201 для программы и ГОСТ Р 34.602 для автоматизированной системы. Есть и другие стандарты, которые достаточно хорошо описывают структуру и содержания таких документов. Но увы, в большинстве случаев эти стандарты описывают спецификации «внешних» требований заказчика к целевому продукту (что, в сущности, верно), т.е. продукт рассматривается как «чёрный ящик», который что-то и как-то делает, и вот эти «что-то» и «как-то» в их внешнем проявлении в ТЗ как спецификации требований и описываются. А вот вопрос о том, может ли быть ТЗ «для разработчика», остаётся открытым.

— Нам нужен дизайн-док. — Какой именно? — Ну...ГДД.

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

Я уже более трёх лет в геймдеве — пусть и как инди-разработчик. У меня своя команда, собранная с нуля. Я учусь в магистратуре по профилю «геймдизайн», прошёл ряд курсов от западных университетов, написал десятки тысяч диалогов, GDD, питч-доков, фич-доков и множество других документов.

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

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

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

Итак, попробуем разобраться.

Привет, Хабр. Я Матвей Лихота, старший Go-разработчик из МТС Web Services. По моему опыту, документация, которую пишут руками отдельно от кода, устаревает уже в момент следующего коммита. Из-за этого мы в команде тратили до 20% времени на поддержание актуальности swagger-документации в десятке микросервисов. И когда ошибки интеграции уже стали привычным фоном, мы все-таки решились и перевернули всё с ног на голову: внедрили Documentation-Driven Development (DDD) — подход в разработке, когда процесс начинается с документации. 

Что за подход и что он дал в итоге, зачем понадобилась утилита oapi-codegen и как мы генерируем Go-код из OpenAPI-спецификаций — подробно рассказал и показал под капотом. 

У вас 20 лет опыта, но ни одной статьи на Хабре. Знакомо? «Не умею писать», «нет времени на оформление», «получается сухо». AI обещает решить эту проблему — но между «скормил тезисы в ChatGPT» и «написал сильную статью» лежит огромный путь.

В статье — конкретный пайплайн из семи шагов: от тезисов в рабочем чате до публикации. Разбираем три слоя технической статьи и честно определяем, где AI реально полезен, а где наверняка галлюцинирует. Отдельно — про фактчекинг: почему чат с веб-поиском проверит лишь 5–10 утверждений из 50, и чем AI-агент принципиально отличается от обычного диалога.

Статья не про «AI напишет за вас», а про то, как превратить экспертизу в текст, не потратив на оформление втрое больше времени, чем на саму работу.

Введение

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

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

Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для ИТ-команд. Эта статья — интервью с Екатериной Ушаковой о ее книге «Если ты — технический писатель». Екатерина Ушакова — одна из узнаваемых фигур в сообществе технических писателей. Она создала техническую редакцию в Ozon, преподает в Университете Иннополис, организует конференции и ведет сообщество руководителей технических редакций.

Сейчас Катя готовится к выпуску книги о современном техническом писательстве. В статье вы узнаете:

📌 Как и зачем Катя решила написать книгу о роли «Технический писатель».

📌 Почему выбрала печатный, а не электронный формат.

📌 Как Gramax помог справиться с редактурой сотен комментариев.

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

Я не умею учиться на курсах. Серьёзно. Когда встала задача собрать портфолио, я пошла в поле: взяла документацию трёх продуктов, прошла путь пользователя, нашла проблемы, посчитала их цену в деньгах и спроектировала решения.

Что получилось:

📌 Bpium — документация вокруг функций, а не задач. Готовый шаблон CRM спрятан в подвале сайта. По моей оценке 90% пользователей его не найдут. Предложила задаче-центричную архитектуру и 5 тикетов в Jira.

📌 DirectAdmin — гайд по миграции с cPanel заставляет администратора импровизировать в 80% шагов. Для почты и DNS инструкций нет вообще. Нашла 5 системных проблем, спроектировала структуру Plan→Do→Check и скрипты-помощники.

📌 AmoCRM — разработчик тратит 48 минут вместо 5 на типовую интеграцию. 860% лишнего времени. От 275 тысяч до 3+ миллионов рублей в год оценочных потерь вендора. Предложила раздел со сценариями, визуальные маркеры и перекрёстные ссылки.

Моя методика (7 шагов): выбрать интересный продукт, найти сценарий пользователя, пройти путь с секундомером, искать паттерны (не опечатки!), посчитать цену в деньгах, спроектировать решение, упаковать в историю.

Главное: я не собирала портфолио под вакансии. Я собирала ответ на вопрос «нравится ли мне эта работа?». А кейсы получились сами.

В статье — полный разбор каждого кейса, схемы «было/стало», BPMN-диаграмма (упрощенная), таблица пяти проблем и чек-лист, по которому вы сможете собрать такое же портфолио.

Всем привет! Я системный аналитик в компании «СИБИНТЕК-СОФТ». Последние несколько лет занимаюсь разработкой ИТ-продуктов и сталкиваюсь с одной и той же проблемой – документация есть, но ее не читают. В чём причина — в лени разработчиков или в плохо написанной документации? Давайте разберёмся.

Важно: речь в статье идёт именно о внутренней технической документации для команды разработки: архитектурных решениях, описании сервисов, API и т.д. Это не про инструкции пользователей или администраторов и не про проектную документацию для заказчика.