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

Вот и обещанная вторая статья по 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. Коллегам-техническим писателем и всем, у кого, как и у меня, нет опыта разработки, но есть желание автоматизировать работу, добро пожаловать под кат.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Приветствую всех! С вами старший системный аналитик, эксперт онлайн-школы по системному анализу Ольги Пономарёвой System Analyst. Статья основана на практическом опыте, в нашей школе мы не просто даем теорию, а любим делиться тем, что действительно работает на проектах.

Разбор legacy-системы без документации кажется сложной задачей. Но это возможно с правильным подходом и современными инструментами. Это руководство даст вам план действий, практические методы и покажет, как использовать ИИ для ускорения работы.

Древнее и сакраментальное RTFM преследует нас повсюду. Волей-неволей мы вынуждены постоянно читать инструкции: к технике, приборам, приложениям, системам.

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

В статье расскажу о пяти важных блоках информации, которые обязательно должно содержать руководство пользователя (оно же User Guide).

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

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

База знаний помогает пользователям быстро понять, какие возможности есть у облачных сервисов — так же, как качественный README объясняет назначение open source‑проекта. 

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

История айтишника, который устал держать рубли на депозите, решил инвестировать в недвижимость в Дубае — фактически купить квартиру в Дубае — и прошёл весь процесс, от первого звонка брокеру до регистрации титула. До старта я гуглил, сколько стоит квартира в Дубае, сравнивал стоимость квартиры в Дубае по районам и спорил с друзьями, где выгоднее купить недвижимость в Дубае. В русскоязычных чатах под хештегом недвижимость Дубай находил свежие кейсы, а аналитика по рынку недвижимость в ОАЭ убедила: пора действовать.

НИИ ПТЭС — один из лидеров российского строительного рынка — как и многие отечественные предприятия столкнулся с необходимостью импортозамещения. Маркетолог компании Евгений Платонов рассказывает, почему инженеры выбрали именно nanoCAD и как был организован путь от тестового периода до успешного внедрения новой САПР в бизнес-процессы.

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

В статье пытаемся разобраться какой ключевой навык аналитика и как его можно проверять на собеседовании...

Приглашаем на премьеру TDMS Фарватер Web — новой системы с удобным веб‑интерфейсом для документооборота и управления проектированием в строительстве.

Дата и формат: 30 сентября в 11:00 (МСК), онлайн, бесплатно