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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пошаговое руководство по использованию Git, Obsidian, Markdown и любимого IDE для разработки требований и трассируемого в них программного кода.

Добрый день! Меня зовут Воронин Николай, я занимаюсь автоматизацией систем отчётности и анализа в ПГК Диджитал.

Моя статья является структурированием личного опыта, полученного в конкретных условиях, он не претендует на статус best‑practice, допускает ситуации, в которых могут существовать более эффективные решения или проблема не стоит в целом.

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

В моём случае речь пойдёт о комплексе нескольких BI систем, существующих параллельно, но сложности вполне могут возникать и в рамках одной, достаточно массивной системы отчётности.

Давайте знакомиться. Я Иван Холодков, старший технический писатель направления производственной документации в YADRO. На производстве документация важна не меньше, чем сборка, тестирование или упаковка. Когда завод работает в режиме 24/7, а у сотрудников нет времени на раздумья, инструкции становятся их основным инструментом.

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

Многие компании в России столкнулись с ситуацией, когда привычные облачные сервисы прекратили работу, а данные оказались заперты в проприетарных форматах, которые без специальных инструментов не открыть.

Концепция «Файл вместо приложения», предложенная Стефаном Ангом, сооснователем Obsidian, предлагает решение: переместить фокус с инструментов на данные, обеспечив их доступность, долговечность и независимость от конкретного ПО.

Всем привет! Меня зовут Катя, я развиваю open-source платформу Gramax для управления технической документацией. В этой статье хочу обсудить, почему подход «Файл вместо приложения» набирает популярность, какие преимущества приносит бизнесу, а также как мы реализуем его в Gramax.

О чем статья:

⚪что такое UI-kit состояний интерфейса и какие компоненты в него входят (экраны успеха, ошибок, пустых состояний и т.д.),

⚪зачем команде его поддерживать,

⚪как собрать и поддерживать UI-kit.

Кому будет полезна статья:

⚪UX-редакторам в растущих продуктах, где нет правил написания текстов и редполитики,

⚪UX-редакторам, которые пришли в давно живущий продукт без налаженных текстов и голоса (англ. «Tone of Voice»),

⚪команде UX-редакторов, которые начали или давно ведут редполитику, но пока не договорились, как должен отзываться продукт в разных состояниях,

⚪дизайнерам, которые работают над одним продуктом, но без UX-редактора в штате.