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

Привет, Хабр!
На связи Маргарита Сорочинская, технический писатель отдела архитектуры в Рунити. Хочу рассказать, как мы в компании подошли к описанию API в Swagger — и почему решили перенести туда всё, что раньше жило в Confluence. А еще поделюсь с вами стартерпаком для описания API в Swagger, пошаговой инструкцией и всеми ссылками, чтобы для вас этот путь был уже более простым :) 

Навигация по тексту:

Добрый день, дорогие читатели!

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

Как вы думаете, сколько человек документирует продукты в Postgres Professional? 50? 100? А вот и нет — всего десять. Рассказываем, как команде техписателей удается управлять сотнями файлов, почему их работа — это квест, и как они успевают контрибьютить в ванильный PostgreSQL.

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

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

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

Но ЧТО же должен создавать автор документации? Что должна в себя включать документация, когда, на каком этапе и в каком объёме она должна создаваться, ЧТО она должна содержать, когда, кому и при каких обстоятельствах она может потребоваться?

В данной статье мы и поразмышляем об этом...

Человеческий мозг эволюционировал для выживания в саванне, а не для анализа распределенных систем. Когда что-то идет не так, наш древний мозг кричит: "Найди угрозу! Накажи виновного! Защити племя!" Эта реакция спасала наших предков от саблезубых тигров, но разрушает современные инженерные команды.

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

Современная документация архитектуры должна решать множество задач одновременно. Она должна быть понятна разработчикам, архитекторам и бизнесу, поддерживать версионирование, интегрироваться в CI/CD процессы и оставаться актуальной.

В этой статье мне хотелось бы порассуждать о такой области ИТ-бизнеса, как документирование ИТ-продуктов – автоматизированных/информационных систем (АС, ИС, АИС и т.п.), а также о том, как применение стандартов отражается на качестве разрабатываемой документации и её восприятии целевой аудиторией читателей.

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

Но при этом неизбежно возникает вопрос – а как создать эту документацию?

Вот и обещанная вторая статья по Docs as code. В части 1 я рассказала про основные подходы создания технической документации. В этой статье я не буду останавливаться на других подходах, вас ждет чистый Docs as code.

Как мы знаем, подход Docs as code основан на принципах и инструментах разработки, поэтому сегодня я расскажу о фундаментальных концепциях разработки, на которых строится понимание подхода Docs as code в моей голове. Выяснив это, все инструменты подхода начинают склоняться к вашим ногам. Погнали!

Привет, Хабр! Пришла делиться новыми статьями, ведь как доклады они не интересны. Буду вещать про связь программирования и технической документации (как обычно), только смещу фокус с похожести на применяемость одного в другом.

Выше я лишь намекнула, о чем пойдет мой разговор, сейчас я распишу подробнее. Часто подход к разработке документации Docs as code воспринимается как что-то тяжеловесное, неповоротливое, сложное и даже страшное. Я постараюсь развеять это мнение или хотя бы повлиять на него. В одну статью я не уложилась, когда писала черновики, поэтому в этой статье я расскажу о существующих подходах к разработке документации (иногда негласных, но все-таки существующих), их особенностях, преимуществах и недостатках. В следующих статьях я расскажу про более практическую часть и использование Docs as code. Держитесь!

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

Теперь разберем подробнее, почему это так важно.
DRC (DesignRuleCheck) — это процесс автоматизированной проверки соответствия проекта печатной платы (PCB) определённым правилам проектирования. Эти правила устанавливаются производителем печатных плат и определяют минимальные допустимые размеры проводников, зазоры между элементами, требования к расположению компонентов и другие параметры.

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

Таким образом:

1. DRC – это мост между вашим проектом и технологическими возможностями производства

Каждое производство имеет свои технологические ограничения:

· Минимальная ширина проводника и зазора. Самое базовое правило. Если вы сделаете дорожку тоньше, чем производство может гарантированно воспроизвести, она будет разорвана или замкнута с соседней.

Всем привет!

В этой статье поговорим об инструменте для моделирования архитектуры в нотации ArchiMate — Archi.

Про саму нотацию и Archi уже написано немало статей, в том числе на Хабре, но вот о плагинах Archi информации заметно меньше. Мне не удалось найти подробных и актуальных материалов, особенно если речь идет о самостоятельной сборке плагинов.

Решил разобраться сам и поделиться результатами небольшого исследования — как собрать плагин для Archi и на что стоит обратить внимание на примере нового плагина coArchi2. Бонусом небольшая детективная история по исходникам.

Электромагнитная совместимость при проектировании печатных плат.

Электромагнитная совместимость (ЭМС) – это не просто этап проверки готовой печатной платы, а фундаментальный принцип, который должен быть заложен в процесс проектирования с самого начала.

Последствия игнорирования ЭМС на этапе проектирования:

1. Нестабильная работа устройства: сбои, зависания, самопроизвольные перезагрузки.

2. Помехи для другого оборудования: ваше устройство может «глушить»Wi-Fi,Bluetooth, создавать помехи другим радиоприборам.

3. Невозможность пройти сертификацию: устройство не получит разрешение на продажу (например, маркировку CE, FCC). В России сертификация ЭМС представлена техническим регламентом Таможенного союза ТР ТС 020/2011 «Электромагнитная совместимость технических средств». Документ действует в странах Таможенного союза (ЕАЭС).

4. Дорогостоящая коррекция: исправление ЭМС на готовой печатной плате – это добавление экранов, ферритовых колец, переразводка печатной платы, что ведёт к задержкам производства и росту стоимости.

Гой еси, Хабр!

Звать меня Артем Клещев, я технический писатель в СберТехе. Работа моя — складывать сказания да инструкции для достославного продукта Platform V DropApp, что как царство-государство Kubernetes да с верной свитой операторов.

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

Привет, Хабр! На связи Галина Чупрова, главный инженер по тестированию в Рунити. Сегодня расскажу, как мы в компании пришли к тестированию документации — и почему этот шаг повысил эффективность тестирования и сэкономил команде нервы.

Предлагаю на ваш суд мой промпт, который я разработала специально для ChatGPT-5. Вы можете загрузить свои конспекты или даже фото конспектов и получите материал: с логичной структурой, подзаголовками, списками, выделением ключевых понятий, вводной частью и резюме. Не выдумывает от себя, если что-то написано неразборчиво, пометит в отдельный блок. Cохраняет авторский стиль, поясняет термины, формирует обзор, основную часть, резюме и список вопросов. Результат оформляется в Markdown: удобно читать, редактировать и публиковать.

Давайте разберем ППРФ № 1300 на молекулы, и разберемся, наконец, что-же там написано. Ниже таблица, в которой разобраны некоторые пункты данного постановления по-отдельности.

Сначала давайте определимся с терминами.

Через весь текст ППРФ речь идет про некое действие (процесс), который называется «передача», и осуществляется над объектом называемом «Информация об инициаторе телефонного вызова» это ни что иное, как «маркировка из 32 символов».

Для начала давайте отдельно разберем пункт 5 постановления, как самый трудночитаемый:

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

Утренний кофе выпит, бутерброд съеден, довольные коты накормлены. Федя сразу включается в работу — дел много, нужно всё успеть. Но для начала нужно обновить локальные исходники разделов из репозитория. Это не первый его релиз. И Фёдор уже привычно запускает синхронизацию.

Напряжение ощущается с самого утра. В рабочем чате постоянно всплывают сообщения: «Забираю исходник раздела с описанием общего алгоритма, буду вносить правки», «Добавил в карту документа пару новых приложений, обновитесь», «Перешлите мне комментарии тестировщика, у меня письмо затерялось». Сегодня не просто очередной рабочий день, сегодня — день релиза...

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

Почему общение становится такой проблемой? Потому что его слишком много, оно хаотично и не имеет единого центра. Вас дергают коллеги, сыплются непонятные задачи, начальство ставит задания вскользь на созвонах, а через месяц интересуется результатом. Информация теряется в почте, чатах и в собственной памяти. А ещё фоном мозг напоминает: "Не забудь, надо сделать то-то и то-то!".

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

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

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

История направления NSR Specification началась в далеком 2021 году, когда мы выпустили Модуль требований — базу знаний по стандартам для строительства и смогли реализовать первую связь с САПР nanoCAD в виде панели подсказок нормативных требований. Для автоматизации разработки и актуализации базы мы реализовали первый инструмент, использующий ИИ-компоненты:  Модуль семантической разметки документа, с функциями выделения границ требований и привязки кодов КСИ. Следом, мы разработали свой текстовый редактор, специально для создания текстов стандартов, организации процесса публичного обсуждения и публикации отдельных требований в базу Модуля требований.  

Но это было только начало. Наша главная цель, ради которой и стартовала работа направления NSR Specification: автоматизация оценки соответствия ЦИМ — требованиям стандартов.

О процессе разработки NSR Модуль семантического анализа «как на духу» мы рассказали вот здесь. Пилотные проекты с гигантами рынка, предоставившими нам свои информационные модели, помогли нам сделать продукт работоспособным. Подробнее об этом можно почитать тут.

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