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

Данный материал создан учеными Национального исследовательского университета "МЭИ" (НИУ "МЭИ") кафедры Автоматизированных систем управления тепловыми процессами (АСУТП). Представленные сведения основаны на результатах исследований и отражают профессиональное мнение авторов.

            Схема пуска и стопа с самоподхватом нужна для того, чтобы при нажатии на кнопку «Пуск» на контакторе, можно было не задерживать эту кнопку. При этом схема продолжит работать, так как контактор подхватил сигнал и теперь напряжение никуда не уйдет, пока не будет нажата кнопка «Стоп». Такая система позволяет надежно и эффективно управлять двигателем.

Лучший способ похоронить базу знаний — это спустить её сверху, обязать всех искать там информацию и бросить в таком состоянии. БЗ только тогда чего-то стоит, когда она вовремя пополняется и актуализируется, когда в ней на конкретный вопрос находится конкретный ответ, когда за информацией не надо бегать по куче ссылок, выискивая крупицы смысла. Когда база знаний не утрачивает своей пользы при росте числа пользователей — как авторов, так и читателей. Только тогда принятие решений на основе знаний будет точным, онбординг новичков будет проходить без задержек, а саппорт будет укладываться в SLA.

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

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

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

Одной из частых задач документирования является документирование баз данных. Это может быть документирование PostgreSQL, Clickhouse, MongoDB и других баз данных. Их все объединяет один простой факт — такую документацию сложно делать вручную. В этой статье я разберу, как создать описание базы данных PostgreSQL с помощью утилиты tbls.

Ситуация: открываете базу знаний и понимаете — что-то с ней не так, и каждый раз кто-то приходит с одними и теми же вопросами. Вы — тимлид/техлид/knowledge-менеджер, который знает ответы на все вопросы. Но времени на работу не остаётся как раз из-за разрешения всяких мелочей. Знакомо?

Привет, Хабр! Меня зовут Анастасия Граф. Я руковожу отделом разработки технической документации в Maxim Technology — компания делает Ride Tech сервис для такси Maxim. Мы первыми в России запустили цифровую платформу. Этот материал готовился по мотивам доклада для TeamLead Conf.

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

Markdown — популярный и удобный язык разметки, но это также и очень ограниченный формат. Поэтому задача написания в Markdown сложной технической документации по ГОСТ, научной статьи с автоматической настройкой оформления для заданного издательства или хорошо оформленного онлайн-учебника может показаться неосуществимой. В этой статье рассмотрим способ работы над научно-техническими статьями и книгами в формате Markdown на основе подхода Docs as Code с учётом строгих ограничений на оформление, используемый Петром Советовым и мной при подготовке учебных материалов в РТУ МИРЭА.

Способ заключается в применении утилиты pandoc для построения дерева абстрактного синтаксиса (AST) Markdown-документа с последующим переписыванием AST набором фильтров на Lua и трансляцией AST в форматы docx и pdf, соответствующие ГОСТ, а также в диалект markdown, совместимый с mdBook, для генерации онлайн-учебника.

Онлайн-версии книг, написанных с использованием описанного подхода, и репозитории с исходным кодом книг опубликованы на GitHub и GitHub Pages: книга по конфигурационному управлению, книга по разработке кроссплатформенных программмных систем.

У многих компаний, которые создают облачные SaaS-решения, рано или поздно может возникнуть запрос от пользователей: «Можно ли поставить ваш продукт у нас на собственной инфраструктуре?», то есть появляется запрос на on-prem версию. Но не каждый SaaS-продукт сразу готов к такому сценарию: чтобы он работал у клиента, его нужно корректно внедрить в инфраструктуру заказчика.

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

В статье разбирается техническая реализация SQLize Embed — легковесного JS-компонента для создания интерактивных песочниц прямо в тексте технических статей. Автор подробно описывает архитектуру решения: от использования MutationObserver для инициализации редакторов на фронтенде до обеспечения безопасности и изоляции запросов в Docker-контейнерах на бэкенде.

Вы узнаете, как реализована поддержка более 20 СУБД (включая PostgreSQL 18, MS SQL 2025 и Oracle 23ai) и как встроить «живые» примеры кода в свой проект всего парой строк HTML.

Всем привет! Я Елена Шустерман, ведущий писатель в РТЛабс. Более 20 лет работаю в сфере ИТ. Есть большой опыт работы программистом и аналитиком, сейчас я технический писатель.

Расскажу, как при подготовке отчётной документации оптимизировать работу с документами, в том числе в MS Word с использованием возможностей MS Excel. А ещё как упростить себе рутину при сборке списков сокращений и определений.

Делю статью на две части. Эта часть — первая. Позже будет вторая часть с описанием других возможностей расширенного фильтра MS Word.

Данный материал создан учеными Национального исследовательского университета «МЭИ» (НИУ «МЭИ») кафедры Автоматизированных систем управления тепловыми процессами (АСУТП). Представленные сведения основаны на результатах научных исследований и отражают профессиональное мнение авторов.

Всем привет! Меня зовут Вадим, и я QA-инженер в IT-компании Intelsy. В динамичных проектах тест‑кейсы часто превращаются в «мёртвый груз»: они быстро теряют актуальность из‑за изменений в функционале, интерфейсе или бизнес‑логике. Результат — устаревшая документация, на поддержку которой тратится больше времени, чем на реальное тестирование. Разберём принципы и техники, позволяющие создавать долговечные тестовые артефакты.

Привет, Хабр! Меня зовут Даниил Смородин, я работаю техническим писателем в Just AI — компании, которая разрабатывает решения на базе искусственного интеллекта. Когда каждый день пишешь об AI, рано или поздно задаёшься вопросом: а можно ли применить его в собственной работе? В этой статье расскажу, как мы автоматизировали подготовку release notes и первичную вычитку с помощью наших продуктов.

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

Но в реальности такие проекты либо не стартуют, либо застревают на пилотах, либо теряют половину функциональности уже по ходу внедрения.

Проблема почти никогда не в платформах и не в подрядчиках.

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

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

Почему так происходит, при чём здесь Greenfield и Brownfield, когда стандарт начинает приносить реальные деньги — в проектах и в ремонтах — и почему начинать стандартизацию нужно именно с PLC-кода, а не с BI, — разбираем на практике.

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.