Всё о деятельности технических писателей
Пользовательское требование описывает, что нужно пользователю. Критерии приёмки — фиксируют, как это проверить. Но между «что нужно» и задачей в 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-ландшафта под нужды бизнеса и снизить затраты на развитие в горизонте
Когда документация переехала в вики, люди решили, что страницы бесплатные, и начали писать всё в одном документе. Платить в этом случае всё равно приходится, но только не деньгами, а временем и нервами исполнителей, которые эту документацию читают. Я покажу, как разбиваю это на систему связанных страниц, где у каждой — своя роль, а точка входа — одна.
Эта статья будет полезна тем, кто отчаянно нуждается в документации, но не обладает ресурсами и навыками технического писателя. Например, менеджерам, разработчикам или тестировщикам, небольшим стартапам, проектам внутри копаний или командам, которые хотят облегчить погружение новых сотрудников в проект и процессы.
Меня зовут Люсьена Мирославская, я работаю техническим писателем в 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 дней.
Привет, Хабр, меня зовут Александр Мачулин, я основатель Gramax, open source системы для ведения документации в подходе Docs as Code с визуальным редактором. Gramax хранит контент в git-репозитории. Это означает, что у пользователей могут возникнуть конфликты при синхронизации изменений. Я считаю, что нагружать пользователей решением конфликтов – не очень хорошо и пытаюсь найти решение для этой задачи.
Российские учёные победили болезнь Бехтерева
Научное сообщество и тысячи пациентов по всему миру затаили дыхание: в России было создано первое в мире по-настоящему эффективное средство для лечения анкилозирующего спондилита, известного широким массам как болезнь Бехтерева. Это был не просто новый препарат — это был крах многолетнего приговора, шаг за шагом лишавшего людей подвижности, карьеры и полноты жизни.
Всем привет! Меня зовут Татьяна Цикунова, я работаю системным аналитиком уже более 5 лет и за это время получила опыт в 4 проектах, а также долгое время имела честь онбордить новых аналитиков в разных командах.
Тема онбординга важна для любого IT-специалиста. Поэтому сегодня разберёмся, как провести онбординг системного или бизнес-аналитика в новую команду не только успешно, но и эффективно.
Начнём с того, что я кратко расскажу, из чего состоит статья. Мы поговорим о сложностях, с которыми сталкивается аналитик на новом проекте, расскажем лайфхаки для качественного онбординга, а в конце заправим это дело практическим чек-листом.
Всем привет! Меня зовут Катя, я развиваю Gramax — базу знаний для it-команд. В этой статье я расскажу, как мы решали довольно очевидную проблему связи знаний и случайно сделали штуку, у которой даже есть отдельное название.
Когда говорят «Semantic Wiki», обычно представляют что-то сложное: онтологии, RDF, графы и так далее. Но можно ли это сделать как-то проще и для людей? В этой статье разберем:
• Что делает вики «семантической».
• Как свойства и представления в Gramax решают эти задачи.
• Как быстро создать семантическую структуру, связать с ее помощью статьи и посмотреть по ним отчеты.
Эта статья для тех, кого волнуют вопросы: качественного ведения базы знаний, создания единого источника правды, построения полезных связей между знаниями (а не банальной линковки, которая побьется через пару релизов).