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

Прошло целых два года, как команда NSR Specification твердо пообещала добиться автоматизации экспертизы цифровых информационных моделей (ЦИМ) за счет создания машинопонимаемых представлений требований стандартов проектирования. На тот момент мы очень хотели регулярно рассказывать о промежуточных результатах, но слишком увлеклись разработкой. Ежедневно возникали новые и новые проблемы, в муках рождались способы их решения, в спешке писались задачи на разработку, когда заканчивались слова мы рисовали картинки, потом, дрожащими руками тестировали новый функционал, с азартом отлавливали баги, умело замаскированные под фичи... Каждый раз нам казалось, что осталось только дождаться свежего релиза, и все, мы победили. Оглядываясь назад, мне все чаще кажется, что мы были немного сумасшедшими, раз взялись за эту задачу. Но это, наверное, к лучшему. Если бы тогда, в 2023 году мы знали обо всех сложностях, с которыми нам предстоит столкнуться, то сегодня не смогли бы похвастаться работающим решением. Теперь то уж точно нам есть о чем рассказать: решение работает и уже обкатано на нескольких пилотных проектах.

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

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

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

Я Дима, работаю техническим писателем в UDV Group, описываю разрабатываемые продукты для внешних и внутренних пользователей.

Задумывались ли вы когда-нибудь о том, кто объясняет сложное так, чтобы было понятно всем? Кто превращает техническую жаргонизированную речь разработчиков в простые инструкции, которые может прочитать любой — от новичка до супер-специалиста?

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

Дисклеймер для тех, кто не смотрел «Друзей»

Моника Геллер — персонаж культового ситкома 90-х, безумно одержимая порядком. Её чек-листы для чек-листов, лейблы на лейблах и фетиш сортировки по цвету и размеру превратили её в мем про педантизм. Но именно Моника в сериале всегда вытаскивала друзей из провалов: когда нужно было за 3 часа организовать свадьбу, найти документы за 5 лет или просто понять, кто последний брал фондюшницу.

В реальной жизни мы живём не в квартире с purple дверью, но законы Моники работают лучше любого скрам-майнд-сета.

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

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

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

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

Компания АО «НижневартовскНИПИнефть» (г. Нижневартовск) решает комплексные задачи обустройства нефтяных и газовых месторождений, расположенных в регионах с различными природными условиями и отличающихся насыщенной промышленной инфраструктурой. Институт постоянно отслеживает новейшие технологии и методы, используемые для совершенствования процессов разработки месторождений нефти и газа, развивая и укрепляя отношения с отечественными и зарубежными научными организациями и разработчиками технологического оборудования.

С помощью nanoCAD Конструкции PS ООО «АРТ» автоматизировало проектирование железобетонных конструкций, что позволило сократить количество ошибок, ускорить процесс армирования и автоматизировать подсчет спецификаций, значительно повысив эффективность работы над проектами.

В общем, решил сделать пет-проект. ЦРМ нормального фрилансера. Сам я ремесленник-одиночка и пользуюсь ограниченным набором инструментов для ведения дел: Google Таблицы, да Windows-заметки. Решил все эти данные свести воедино в рамках собственной црмки.

Я не разработчик, а проектировщик интерфейсов (UX/UI-дизайнер). Опыта в программировании совсем немного. Поэтому пет-проект был мне особенно интересен. Я уже двадцать лет готовлю проектную документацию для других — а в этот раз для себя.

Сейчас расскажу, как я довёл идею до продукта, как мне в этом помог ChatGPT и почему это было иногда весело и интересно, но большую часть времени — скучно и грустно.

Краткий гайд по наведению порядка HTTP status code и тому, как действовать если реальность становится по-настоящему пугающей.

Представим совершенно невероятную ситуацию: компания-стартап почувствовала потребность в системном аналитике и наняла своего первого специалиста. Знакомство с командой прошло позитивно, аналитик получил все необходимые доступы сразу. Он  изучает продукт компании и получает первую задачу: спроектировать новый API endpoint с применением архитектурного стиля REST. 

Он запускает несколько методов… и дальше начинает происходить что-то сверхъестественное:

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

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

Привет, Хабр! Меня зовут Яна, я работаю бизнес-аналитиком в ITSM 365. Как добиться, чтобы все хотели пройти в вашу библиотеку, расскажу на основе нашего собственного опыта.

В мире разработки мы постоянно сталкиваемся с технической документацией — она повсюду, от спецификаций API до архитектурных решений. И мы хотим, чтобы документация была структурированной, актуальной и удобной… но в реальности чаще имеем дело с хаотичным набором разрозненных материалов, которые теряются между Confluence, почтой и Google Docs, стремительно устаревают и выглядят небрежно, с «плывущими» таблицами и запутанной структурой. Представили этот беспорядок?

Хорошая новость: есть способ автоматизировать и стандартизировать документацию, сделав её такой же управляемой, как код — через модель docs as code.

В статье вместе вспомним базовые принципы этого подхода, расскажем про наш опыт документирования и поделимся репозиторием с готовым шаблоном LaTeX для максимально быстрого старта без установки зависимостей!

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

Привет, Хабр! Проблема рассинхронизации автотестов и тестовой документации знакома многим. Код постоянно меняется, а кейсы в Confluence — нет. В итоге документация становится бесполезной, а время команды тратится на выяснение того, что же на самом деле проверяет тот или иной тест.

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

Группа компаний «Алгоритм» перешла с 2D-проектирования в AutoCAD на сквозную работу в BIM-решениях nanoCAD. Внедрение единой платформы (Платформа nanoCAD, конфигурация nanoCAD BIM Конструкции, nanoCAD GeoniCS, nanoCAD Конструкции PS, инженерные модули) сократило сроки проектирования вдвое, уменьшило коллизии на 82% и сэкономило 5 млн рублей на материалах. Пилотным проектом стал 16-этажный жилой дом в Калуге, где все разделы — от архитектуры до инженерии — создавались в цифровой среде с автоматизацией расчетов и проверкой коллизий.

Привет! Меня зовут Глеб Свистунов, в YADRO я руковожу разработкой производственной документации — то есть документации, сопровождающей производство. Мы разрабатываем документацию для технологических процессов: руководства по сборке, прошивке, тестированию и другие документы по технически сложным устройствам, у которых могут быть сотни или даже тысячи разных конфигураций.

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

Сборщики серверов на конвейере тоже получают для сборки лоток с деталями. Но в отличие от «сокола», который мы будем неспешно собирать долгими зимними вечерами, здесь у сборщика есть строго 20 минут на один сервера, после чего уже нужно приступать к следующему. Поэтому нужна еще более четкая инструкция, на понимание и воспроизведение которой требуется минимум усилий и времени. 

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

Представьте мир, где каждое ваше платежное поручение теряется между банковскими системами. Где клиент не может оформить кредит, потому что «что-то сломалось». Где регуляторы штрафуют за несоответствие данных, а ИТ-команда разводит руками: «Но бизнес же не объяснил, что ему нужно!»

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

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

Привет! Меня зовут Александр, я SDET-специалист в SimbirSoft. В этой статье я расскажу, как можно покрыть разрабатываемую часть проекта автотестами на ранних этапах его разработки, если в команде отсутствуют аналитики и присутствуют задокументированные требования только по основному функционалу. Эта статья будет интересна как джунам, так и техническим специалистам middle и выше, а также руководителям команд (team leads) и техническим лидам (tech leads).

Я поделюсь тем, как в такой ситуации были настроены процессы в нашей команде. Мы работаем над проектом с утвержденной микросервисной архитектурой с внутренними и внешними сервисами. Команда работает по Scrum-методологии и состоит из тимлида, разработчиков сервисов, QA и SDET-специалистов. От заказчика поступила лишь основная информация о том, что должен делать продукт и на каких платформах его можно будет использовать. Именно эта информация и была задокументирована в виде требований.

Подробно разбираем инструменты для работы с выносками в nanoCAD BIM Электро — от базовых возможностей до создания пользовательских шаблонов.

Я часто сталкиваюсь с тем, что дизайнеры отказываются от проектов с нечёткими вводными. А зря. Такие проекты — идеальный способ вырасти в профессии, если уметь правильно организовать процесс. В статье — как я это сделал, какие документы оформил, как застраховался от «нравится/не нравится», и чем это закончилось.

26 июня мне в Телеграм написал потенциальный клиент.

— Добрый день! Хочу пообщаться с вами на тему возможного сотрудничества по поводу UI/UX. Если кратко, это редизайн для электронного прибора (радиолюбительский КВ/УКВ приемопередатчик). Проект открытый, текущий дизайн я делал сам, но хочу переделать. То, что сейчас сделано, можно посмотреть на канале проекта.

Первая мысль: «Не мой клиент». Во-первых, я UX-дизайнер и привык делать прототипы и документацию, а не рисовать редизайн. Во-вторых, если проект открытый, денег там, наверное, не заработаешь.

Вторая мысль: «Зато интересно! Интерфейс для физического устройства. Даже если не смогу взяться за работу — познакомлюсь с интересным человеком. Может, порекомендую кого».

В общем, я точно не предполагал, какой у истории будет конец.

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