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

Помните момент, когда вы впервые попробовали 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 и т.д. Это не про инструкции пользователей или администраторов и не про проектную документацию для заказчика.

Как обеспечить устойчивое развитие IT-ландшафта под нужды бизнеса и снизить затраты на развитие в горизонте

Изображение от rawpixel.com на Freepik

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

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

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

Проблема: никто не знает, кто кого вызывает

В 2012 году биржевой брокер Knight Capital потерял $460 миллионов за 45 минут.
Причина — активация устаревшего модуля, который начал массово размещать ордера.
Отчёт SEC указал на ключевую ошибку:

Управление строительными проектами и документацией становится проще с системой TDMS Фарватер Web. Для быстрого освоения системы команда «Нанософт» подготовила серию коротких обучающих видео.

Кому это будет полезно? Техническим директорам, руководителям проектов, ГИПам, ГАПам, главным специалистам, проектировщикам, BIM-менеджерам и ИТ-специалистам.

1. Установка и настройка системы TDMS Фарватер Web

От лицензирования до первого запуска. Показываем все ключевые шаги за семь минут. Смотреть видео

2. Как настроить права доступа сотрудников?

Управление уровнем доступа в зависимости от роли (кто и что может делать в системе): от администратора до проектировщика. Смотреть видео

3. Как просматривать файлы из TDMS Фарватер Web?

Работа с документами проекта: просмотр PDF прямо в системе, скачивание и права доступа. Смотреть видео

4. Как создать проект с разбивкой на стадии?

Настройка этапов, объектов и документации. Смотреть видео

5. Как создавать и визуализировать рабочий процесс?

Настройка последовательности согласований, проверок и утверждений позволяет контролировать статус каждой задачи. Смотреть видео

6. Как автоматизировать работу с замечаниями?

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

Бесплатная пробная версия

Оцените все возможности TDMS Фарватер Web на практике – получите бесплатный доступ на 30 дней.

Скачать пробную версию TDMS Фарватер Web

Привет, Хабр, меня зовут Александр Мачулин, я основатель Gramax, open source системы для ведения документации в подходе Docs as Code с визуальным редактором. Gramax хранит контент в git-репозитории. Это означает, что у пользователей могут возникнуть конфликты при синхронизации изменений. Я считаю, что нагружать пользователей решением конфликтов – не очень хорошо и пытаюсь найти решение для этой задачи.

Российские учёные победили болезнь Бехтерева

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