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

1 Операционная надежность (надежность операций, процессов, функций)

Регулятор (ЦентоБанк) уже несколько лет ведет «крестовый поход» под знаменем «Операционная надёжность»: выпускает «одноименные» Положения (850-П / 787-П, 779-П), Стандарты Банка России (СТО БР БФБО-1.5-2023), ГОСТы (ГОСТ 57580.3 / 57580.4, с его участием), а также методические рекомендации (18-МР) и формы обязательной отчетности по «Операционной надёжности» (operational resilience).

Под знаменем «Операционная надёжность» - делается попытка «скрестить» (где-то «ежа с ужом», но сама идея достойная) бизнес-архитектуру (архитектуру процессов, как технологических, так и бизнес – хотя разделение их не понятное), EA (enterprise architecture) / ИТ-архитектуру, ITSM (CMDB, управление инцидентами, в том числе, инцидентами операционной надежности), информационную безопасность (вкл. ГОСТ 57580.1 / 57580.2), надежность / отказоустойчивость / ОНиВД, риск-менеджмент (опер-риски, 716-П), импортозамещение (ФТК). Подобный «единый узел» - это проекции «одного и того же» на разные плоскости (EA, BPM, GRC, ИБ, ITIL и др.) с разными словарями / концепциями, поэтому формализовать его видимо равносильно притчи / сценарию «Вавилонская башня». Однако «язык графа» сближает такое восприятие и снижает барьер сложности.

Далее будем говорить только о Форме 0409072 (далее ф072) — «Сведения о показателях операционной надёжности кредитной организации и применяемых ею информационных технологиях при осуществлении банковской деятельности и деятельности в сфере финансовых рынков», точнее о ее части – шифре \ шифровке архитектуры предприятия. «Операционная надёжность» - это всего лишь контекст. 

Использование подхода "Docs as code" на примере ODS проекта для автоматизации процессов создания и поддержки технической документации.

Проекты в АСУ ТП обычно заканчиваются успешно.

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

Новые инженеры месяцами «входят в тему», модернизации откладываются, знания живут в головах отдельных людей, а слово «стандарт» сводится к упоминанию ГОСТ и ЕСКД, которые никак не помогают в реальной эксплуатации.

Почему так происходит?

Потому что во многих компаниях стандарт находится ниже проекта, а не выше него.

Эта статья — не про ГОСТы, не про шаблоны и не про конкретные контроллеры.

Она про то, почему стандарт АСУ ТП должен быть частью бизнес-системы предприятия, как он влияет на простои, деньги, людей и зависимость от подрядчиков — и почему отсутствие стандарта обходится дороже, чем его внедрение.

Если вам знакома ситуация, когда система «работает, но лучше её не трогать» — эта статья для вас.

В мире стартапов существует документ, который в США считается одним из краеугольных камней при создании новой компании - Founders’ Agreement (Соглашение основателей). В нём фиксируются роли, доли, обязанности и основные правила игры между создателями проекта. В России же аналогичные вопросы обычно решаются позже, при подписании Корпоративного договора уже после регистрации ООО. Но между моментом, когда идея выстрелит и официальным рождением юрлица лежит критически важный период. Именно в это время команда уже несёт затраты: на хостинг, домены, рекламу, разработку прототипа и так далее. Для этой фазы и нужен отдельный документ - своего рода предварительный договор, фиксирующий все договорённости «на берегу».

Несмотря на очевидную практическую пользу, в России такая практика пока не прижилась. По итогам опросов основателей и инвесторов выяснилось, что практически никто из них не подписывал подобный документ на самом старте, хотя многие признали, что это могло бы избавить от будущих конфликтов. Видел, что иногда подписывают "ПОНЯТИЙНОЕ СОГЛАШЕНИЕ ", но прям, очень редко. Так почему же Founders’ Agreement так важен, особенно в российской реальности?

Сделал российский аналог «Соглашение основателей».

Привет, Хабр! Это вторая статья про BPMN, в которой мы переходим от теории к практике.

В первой части мы разобрали недостатки стандарта BPMN, которые важно учесть до начала моделирования, чтобы сделать проектирование процессов понятным, однозначным и эффективным.

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

Недавно к нам в компанию взяли нового сотрудника на должность программист или разработчик MS Dynamics AX 2012 (для начала выбрали версию 2012, но с перспективой его быстрого переключения на любые версии, включая D365 FO) — стажёр Воякс Иван Иванович (он же Woyax).

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

В этой статье я расскажу об основных достоинствах DITA.

Борьба с последствиями плохого ТЗ иногда ценится выше, чем работа по его предотвращению.

Кратко о парадоксе: все ругают костыли и авралы, но они повторяются вновь и вновь. Значит, это кому-то нужно? Посмотрим на экосистему проекта не с технической, а с экономической и карьерной точек зрения.

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

Всем привет, меня зовут Алекс Гусев. В этой публикации я продолжаю формализовать свой личный опыт взаимодействия с агентом OpenAI Codex при разработке программного обеспечения. Речь пойдёт о практическом использовании файлов AGENTS.md как инструмента организации контекста проекта в долгоживущих и структурно сложных системах.

Реставрация 35-метрового храмового купола с его сложнейшими сводами требовала нестандартного подхода: возвести строительные леса, точно повторяющие криволинейную геометрию памятника и при этом абсолютно устойчивые без крепления к стенам. Выполнение этой задачи с помощью 3D-моделей вместо десятков чертежей, сокращение сроков проектирования в 3 раза и сложнейшая конструкция строительных лесов, рассчитанная на собственную устойчивость без единого анкера.

Все это – результат одного решения, которое многие российские инженеры до сих пор боятся принять: отказ от AutoCAD в пользу nanoCAD.

Документация может спасти проект или убить его, если подойти к ней без дисциплины

В этой статье системный аналитик Влад показывает, как применять инженерные принципы — SRP, SSOT, ООП — не к коду, а к аналитике, описанию систем и документированию решений.

Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту Platform V DropApp — решению для управления контейнерными приложениями. Наша команда работает в парадигме Docs-as-Code.

Мы столкнулись с проблемой: при каждом изменении продукта нам нужно было менять документацию сразу в нескольких репозиториях — для каждого исполнения продукта. Но мы нашли решение, как оптимизировать процесс. И хотим поделиться рекомендациями по ведению единого источника в Docs-as-Code — будет полезно тем, кто хочет шаблонизировать документацию и сэкономить время для творческих задач.

В статье покажу, как построить удобную архитектуру репозитория продукта с применением шаблонов и MyST-разметки в парадигме Docs-as-Code. Расскажу, как вместо поддержки нескольких разрозненных комплектов документации создать библиотеку шаблонов с общим контентом. Надеюсь, что опыт нашей команды поможет вам избежать ошибок и лишних шагов.

Как автоматизировать создание технической документации для сотен мер в OLAP-проекте? Рассказываю про систему, которая связывает LangGraph, MCP-сервер и Cursor CLI в единый конвейер генерации спецификаций.

Агент извлекает список мер через локальную LLM (с фалбэком на regex), последовательно обрабатывает каждую через циклический граф состояний и автоматически трассирует поток данных от Power BI мер через DWH представления до хранимых процедур.

Практический кейс из BI-аналитики: от 15-20 минут ручной работы на меру до полной автоматизации. В статье — эволюция архитектуры от простого MCP-сервера до продакшн-решения с детальным логированием каждого шага.

GitHub репозитории прилагаются.

Привет, Хабр!

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

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

OpenAPI — это открытая спецификация для описания REST API. Изначально она называлась Swagger, но в 2016 году была переименована в OpenAPI Specification и передана под управление OpenAPI Initiative. На данный момент Swagger — это набор инструментов для работы со спецификацией OpenAPI (Swagger UI, Editor, Codegen).

В OpenAPI определяются пути, параметры, тела запросов и ответов, коды статусов, схемы данных, типы аутентификации. В статье мы рассмотрим спецификацию OpenAPI версии 3.0: разберем из каких обязательных блоков она состоит и как правильно описывать типы данных и параметры запросов.

Мы привыкли к классическому набору любого сайта: robots.txt экономит ресурсы сервера, запрещая поисковикам сканировать мусорные страницы, а sitemap.xml, наоборот, скармливает поисковикам каждую доступную страницу для полной индексации.

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

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

В сентябре 2024 года Джереми Ховард (создатель fast.ai) предложил решение в виде стандарта /llms.txt. Давайте разберемся, как он работает, чем отличается от llms-full.txt, какую пользу из этого могут извлечь разработчики и как быстро добавить его поддержку в свой проект.

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

На практике многие специалисты не обладают достаточным знанием принципов взаимодействия инструментов BIM-модуля и таблиц. Отсутствие специализированного инструмента требует комплексного подхода – понимания логики связей между элементами модели и средствами автоматизации оформления проектных документов.

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

С развитием нашей компании и выходом на новые рынки (а магазины Fix Price работают не только в России, но также в ряде стран ближнего зарубежья и даже в ОАЭ) значительно увеличилось число задач по согласованию первичных договоров аренды. За 2024 год на согласование контролёру поступило 919 новых договоров аренды, а за первую половину 2025 года — уже 438. Поскольку с первого раза договоры в большинстве случаев не согласовываются, они возвращаются на доработку, и количество задач специалиста возрастает в разы.

Привет, Хабр. Меня зовут Мария Рылик, я — старший контент-менеджер группы управления пользовательским опытом веб-поддержки «Лаборатории Касперского». И полтора года назад я столкнулась с распространенной в техписовских кругах проблемой: децентрализованной базой знаний. Чтобы найти инфу по работе с конкретным продуктом, приходилось по крупицам искать ее в разных статьях, в большинстве своем имеющих мало общего с конкретной задачей, которую я пыталась решить.

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

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