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

Привет, Хабр! Проблема рассинхронизации автотестов и тестовой документации знакома многим. Код постоянно меняется, а кейсы в 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-редактора в штате.

Всем привет! В процессе обновления инфраструктуры сопровождения наших программных решений мы получили интересный опыт, которым хотим поделиться. Эта статья не просто пошаговая инструкция, а практический разбор того, как мы выстроили процесс подготовки технической документации на основе MkDocs Material, автоматизировали его через GitLab CI/CD и встроили полученный результат в сайт на Битрикс. Наш опыт окажется полезным тем, кто хочет навести порядок в документации и сделать её частью полноценного dev-процесса.

Всем привет. В последнее время перевод текстов с одного языка на другой уже не вызывает такой головной боли, как раньше: есть несколько качественных онлайн-переводчиков, есть большие нейросети, которые тоже можно попросить перевести текст, — в общем, варианты есть, их довольно много, и они выдают вполне приемлемый результат. Но у всех них есть одно ограничение: они работают онлайн (удалённо). Для кого-то это ограничение несущественно, а для кого-то может быть критично. Мне же просто захотелось иметь что-то, что сможет переводить тексты на хорошем (современном) уровне офлайн (сугубо на моём компьютере). Ну, люблю я, когда всё, что мне нужно, может работать и локально тоже. В общем, ниже я делюсь с вами тем, что мне удалось в итоге собрать, запустить и даже получить удовлетворяющий меня результат.

Опытного конструктора сложно чем‑то удивить, но давайте попробуем вспомнить то захватывающее чувство, когда открываешь крышку механизма, не имея вообще никакого понятия о том, что внутри. Душа замирает, в глазах — предвкушение, в голове — мысли типа «надеюсь, это не очередная китайская импровизация на тему „как сделать сложно, когда можно просто“». Сегодня мы поговорим о магазине инструментов для металлорежущего станка.

Запуск любого производства, будь то сервера для дата-центра или бытовой электроники, строится на трёх ключевых столпах: техническая документация (ТД), тестовая оснастка (ТО) и тестовое программное обеспечение (ТПО). Эти три элемента — основа реализации массового производства: от первого прототипа до серийной партии. Но довести их до совершенства практически невозможно. Всегда можно сделать что-то лучше: добавить новые функции в ПО, сделать новый чертёж в ТД или улучшить функциональность тестовых стендов. Однако жесткие сроки, бюджеты и нехватка ресурсов заставляют выбирать, где быть идеалистом, а где — прагматиком.

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

Привет, я — Таня Кириллова, технический писатель команды развития безопасности контейнеров в Cloud.ru.

На конференции Techwriters Days 2 Семён Факторович, основатель и руководитель компании documentat.io, в своем докладе Техписатель-2025 предложил ввести специализации для профессии «Технический писатель». В качестве одной из таких он выделил направление Cloud-техписатель. 

Чем Cloud-техписатель отличается от обычного технического писателя? Тем, что извлекает информацию из голов разработчиков и самих сервисов, адаптирует собранную информацию для пользователей, разрабатывает практические сценарии совместно с девопсами, работает с документацией, как с кодом, документирует API, пишет Release Notes… и все это для облачных сервисов.

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

Добрый день, уважаемые читатели! Не так давно я проводил внутрикорпоративное мероприятие о том, как правильно применять чат-ботов, чтобы немного ускорить офисную рутину. Мероприятие очень понравилось аудитории, поэтому я решил переработать презентационный материал в статью - вдруг он принесет пользу еще кому-нибудь?

Если вы уже используете приемы промт-инжиниринга - то, скорее всего, вы не найдете для себя ничего нового. Статья больше рассчитана на тех новичков, которые лишь «что-то слышали» о больших языковых моделях, но не используют их в работе, поскольку это «что-то на ITшном», «не понятно, как это может мне помочь», «я слишком занят, чтобы разбираться самому». Можете переслать эту статью вашим офисным коллегам 💼.

Итак, поехали!

Всем привет, с вами Анастасия Жилкина, системный аналитик ГК Юзтех. На данный момент работаю в команде, которая занимается реализацией и развитием онлайн-оплат на сайте. В этой статье хочу рассказать о процессе ревью документации, который мы внедрили в команде, и о том, какие ощутимые плюсы это дало как в качестве итоговых решений, так и в командной работе в целом.

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

Всем привет. Меня зовут Татьяна Цикунова. Я системный аналитик в компании МойСклад. В этой статье расскажу о том, как организовать оперативный обмен информацией между участниками проекта и поддерживать документацию в актуальном состоянии Отдельное внимание уделю работе с таск‑трекерами — подробно опишу шаблон тикета, который успешно используется в нашей компании. Однако — если вы работаете без трекера задач, например, в ворд‑файлах, суть от этого не меняется ‑такой подход работает и с другими инструментами.

Я документирую системы больше 3 лет, и за это время успела поработать в разных сферах.. Начинала в финтехе, где успела поработать в разных командах. Потом перешла в МойСклад — здесь углубилась в e‑commerce направление. Сейчас вместе с командой делаем интеграции с интернет‑магазинами и маркетплейсами. За годы работы я убедилась, что не существует единого стандарта ведения документации — каждая компания и даже отдельные команды внутри одной организации вырабатывают свои подходы. маркетплейсами. В разных компаниях свой подход к ведению документации, даже в разных командах одной компании бывают разные подходы.

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

В статье рассматривается опыт команды технических писателей Deckhouse по внедрению автоматизированной проверки орфографии в документации. Описываются причины, по которым проверка текста является важной частью работы с документацией, а также анализируются различные подходы к решению этой задачи: от ручной проверки до автоматизации. Подробно разбираются этапы выбора и интеграции инструмента Hunspell в пайплайн CI/CD, особенности работы с различными форматами файлов (Markdown, HTML, YAML), настройка контейнерной среды и создание кастомного словаря терминов. Приводятся практические примеры реализации и результаты автоматической проверки в процессе работы с документацией.