Всё о деятельности технических писателей
Документация может спасти проект или убить его, если подойти к ней без дисциплины
В этой статье системный аналитик Влад показывает, как применять инженерные принципы — SRP, SSOT, ООП — не к коду, а к аналитике, описанию систем и документированию решений.
Привет, Хабр! Я Артём Клещев, технический писатель в СберТехе. Я пишу документацию к продукту Platform V DropApp — решению для управления контейнерными приложениями. Наша команда работает в парадигме Docs-as-Code.
Мы столкнулись с проблемой: при каждом изменении продукта нам нужно было менять документацию сразу в нескольких репозиториях — для каждого исполнения продукта. Но мы нашли решение, как оптимизировать процесс. И хотим поделиться рекомендациями по ведению единого источника в Docs-as-Code — будет полезно тем, кто хочет шаблонизировать документацию и сэкономить время для творческих задач.
В статье покажу, как построить удобную архитектуру репозитория продукта с применением шаблонов и MyST-разметки в парадигме Docs-as-Code. Расскажу, как вместо поддержки нескольких разрозненных комплектов документации создать библиотеку шаблонов с общим контентом. Надеюсь, что опыт нашей команды поможет вам избежать ошибок и лишних шагов.
Как автоматизировать создание технической документации для сотен мер в OLAP-проекте? Рассказываю про систему, которая связывает LangGraph, MCP-сервер и Cursor CLI в единый конвейер генерации спецификаций.
Агент извлекает список мер через локальную LLM (с фалбэком на regex), последовательно обрабатывает каждую через циклический граф состояний и автоматически трассирует поток данных от Power BI мер через DWH представления до хранимых процедур.
Практический кейс из BI-аналитики: от 15-20 минут ручной работы на меру до полной автоматизации. В статье — эволюция архитектуры от простого MCP-сервера до продакшн-решения с детальным логированием каждого шага.
GitHub репозитории прилагаются.
Привет, Хабр!
В детстве портовый кран представлялся мне исполинским жирафом. Длинные ноги его портала стояли на пирсе. А под ними сновали, невероятным образом ставшие крохотными, железнодорожные вагоны. Свою вытянутую желтую шею-стрелу, покрытую темными пятнами ферм, неспешно склонял он над раскрывшейся пастью трюма рыболовного судна-кашалота, отнимая его богатый улов. Жилы стальных канатов звенели от напряжения, настолько тяжела была его работа. Жираф издавал электрический вой, сражаясь за свою добычу.
И вот, спустя многие годы меня продолжают восхищать конструкции советских машин. Но вижу теперь я за ними не те фантазии из детства, а гений человеческой инженерной мысли. И в этой статье я предлагаю вам насладиться технической эстетикой архивных чертежей и конструкторских решений инженеров прошлого.
OpenAPI — это открытая спецификация для описания REST API. Изначально она называлась Swagger, но в 2016 году была переименована в OpenAPI Specification и передана под управление OpenAPI Initiative. На данный момент Swagger — это набор инструментов для работы со спецификацией OpenAPI (Swagger UI, Editor, Codegen).
В OpenAPI определяются пути, параметры, тела запросов и ответов, коды статусов, схемы данных, типы аутентификации. В статье мы рассмотрим спецификацию OpenAPI версии 3.0: разберем из каких обязательных блоков она состоит и как правильно описывать типы данных и параметры запросов.
Мы привыкли к классическому набору любого сайта: robots.txt экономит ресурсы сервера, запрещая поисковикам сканировать мусорные страницы, а sitemap.xml, наоборот, скармливает поисковикам каждую доступную страницу для полной индексации.
Однако ситуация изменилась, когда сайты начали читать не только поисковые роботы, но и языковые модели. Для них существующие стандарты не подходят: sitemap избыточен и ресурсоёмок, а HTML-код создаёт слишком много шума.
Понадобился новый способ доставки актуального, очищенного контекста в сжатом виде специально для AI-агентов и языковых моделей.
В сентябре 2024 года Джереми Ховард (создатель fast.ai) предложил решение в виде стандарта /llms.txt. Давайте разберемся, как он работает, чем отличается от llms-full.txt, какую пользу из этого могут извлечь разработчики и как быстро добавить его поддержку в свой проект.
Одним из ключевых этапов процесса проектирования является формирование ведомостей отделки помещений. При том что в программе nanoCAD BIM Строительство полноценная работа с многослойными конструкциями строительных поверхностей реализована еще не полностью, пользователи уже сегодня могут эффективно решать эту задачу с помощью встроенных таблиц nanoCAD.
На практике многие специалисты не обладают достаточным знанием принципов взаимодействия инструментов BIM-модуля и таблиц. Отсутствие специализированного инструмента требует комплексного подхода – понимания логики связей между элементами модели и средствами автоматизации оформления проектных документов.
В этой статье мы подробно рассмотрим, как с использованием стандартных инструментов программы nanoCAD BIM Строительство можно создать полуавтоматическую ведомость отделки, сохранив при этом корректность данных и возможность их обновления.
С развитием нашей компании и выходом на новые рынки (а магазины Fix Price работают не только в России, но также в ряде стран ближнего зарубежья и даже в ОАЭ) значительно увеличилось число задач по согласованию первичных договоров аренды. За 2024 год на согласование контролёру поступило 919 новых договоров аренды, а за первую половину 2025 года — уже 438. Поскольку с первого раза договоры в большинстве случаев не согласовываются, они возвращаются на доработку, и количество задач специалиста возрастает в разы.
Привет, Хабр. Меня зовут Мария Рылик, я — старший контент-менеджер группы управления пользовательским опытом веб-поддержки «Лаборатории Касперского». И полтора года назад я столкнулась с распространенной в техписовских кругах проблемой: децентрализованной базой знаний. Чтобы найти инфу по работе с конкретным продуктом, приходилось по крупицам искать ее в разных статьях, в большинстве своем имеющих мало общего с конкретной задачей, которую я пыталась решить.
Из-за этого в поддержку приходилось обращаться даже в несложных ситуациях. В результате поддержка, вместо того чтобы использовать свое время для решения действительно сложных, специфичных проблем, была постоянно перегружена однотипными и достаточно распространенными вопросами, ответы на которые можно было бы поместить в отдельную статью. И все из-за отсутствия систематизированного подхода.
В этой статье я расскажу, как мы с командой провели генеральную уборку баз знаний, наступили в процессе на всевозможные швабры грабли, но в итоге помогли и юзерам продуктов, и нашему саппорту: базами знаний стали активно пользоваться, снизилось количество итераций общения по проблеме от первого запроса саппорту до окончательного решения.
Рассмотрим практический разбор слабых мест в технических заданиях на разработку систем, сервисов и т.д.
Идеальное ТЗ — утопия, но многие болезненные моменты и конфликты на стадии приемки можно предсказать и минимизировать. Часто они возникают не из-за злого умысла, а из-за слепых зон в документе.
GraphQL API — это мощно, но как его документировать, чтобы разработчики остались довольны? В этой статье — готовый план действий. Мы начнём со сравнения GraphQL и REST, затем покажем, как с помощью комментариев и примеров кода превратить схему в наглядное руководство. Вы узнаете, как улучшить GraphiQL Playground подсветкой синтаксиса и создать статический справочник, если Playground недоступен. В конце вас ждёт учебный репозиторий для тренировок на реальном API.
Сегодня мы поговорим о том, как развивается платформенная команда «Спортмастера». Речь пойдёт о подходе к организации фронтенд-приложений, который получил название FEOD — Fractal Entity Oriental Design.
Привет, Хабр! Давайте знакомиться! Меня зовут Дима. Я много лет работаю системным аналитиком.
За моими плечами – десятки проектов по разработке и внедрению программного обеспечения, где я не только проектировал, но и проводил ревью процессов других аналитиков и специалистов заказчика. Кроме того, регулярно проводил обучение по нотации BPMN (Business Process Model and Notation).
В процессе работы я активно изучал статьи, книги, стандарты и проходил курсы по проектированию процессов. Для маленьких учебных задач с несколькими операция и условиями эти материалы были очень полезны. Но когда дело доходило до реальных бизнес-процессов – они не помогали.
Именно поэтому в нескольких статьях я решил поделиться своим практическим опытом и размышлениями по проектированию схем бизнес-процессов в нотации BPMN. Надеюсь, что они помогут аналитикам и тимлидам быстрее изучить нотацию BPMN и начать правильно её использовать.
Проанализировав много статей по BPMN на хабре, сайтах онлайн школ и редакторов моделей процессов я увидел, что большинство начинается однотипно с того, какой это классный стандарт, как он необходим каждой компании. Чтобы внести небольшое разнообразие и не повторяться я, начну рассматривать BPMN с его недостатков. Я уверен, что аналитикам и тимлидам, которые хотят внедрять новый инструмент, хочется в первую очередь понять его ограничения и недостатки.
Отдельно хочу обратить внимание на ловушку, в которую попадают даже опытные аналитики и тимлиды при работе с BPMN на реальных проектах. Если у них не получается отобразить процесс элегантно, то появляются сомнения «Если BPMN так хвалят во всех статьях, и он используется всеми специалистами, значит проблема во мне и моих профессиональных способностях?!». В этой и следующих статьях по проектированию процессов я постараюсь развеять эти сомнения, чтобы у аналитиков, попавших в такую ситуацию, было больше шансов сохранить веру в себя, не выгореть и успешно завершить проект.
За последние месяцы наш конструкторский отдел получил большое количество запросов на проектирование защитных ограждающих конструкций (ЗОК) для самых разных объектов: промышленных цехов, технологических площадок, складских комплексов. Спрос растёт, и речь уже идёт не о единичных проектах, а о системном подходе к защите критичной инфраструктуры от беспилотных летательных аппаратов.
Привет, Хабр! Уверен, у вас тоже такое бывало: сидишь в проде, сервис падает, а нужного ответа нет ни в Confluence, ни в старых чатах. В итоге бесконечный скролл в «телеге», повторы вопросов в почте и потерянные часы на поиски того, что кто-то уже когда-то решал. Мы уперлись в эту проблему лбом и поняли, что нам нужен инструмент, который аккумулирует знания и делает доступными.
Меня зовут Денис Селков, я техлид разработки внутреннего Q&A‑портал МТС DevTools Stack. С помощью этого продукта мы упорядочили накопление знаний, и в этом материале я покажу, что дает такая относительно простая механика и как ее можно прокачать с помощью ИИ-инструментов.
В данной статье я хочу поделиться опытом и рассказать о том, как системным аналитикам улучшить Sequence-диаграммы (диаграммы последовательностей) с помощью лучших практик.
Я покажу, как некоторые подходы из мира программирования (те самые best practices и идеи из Clean Code) помогают рисовать sequence-диаграммы чище и понятнее.
Какие главные проблемы технической документации? Во-первых, ее нет, во-вторых, если она есть, то не актуальна.
Давайте порассуждаем, как мы можем попытаться упростить себе жизнь при создании документации, а главное увеличить ее актуальность и качество.
Существует три класса задач, которые решает техническая документация:
1. Описать наши требования к системе и принятые решения
2. Описать текущее состояние системы
3. Объяснить пользователю, как работать (\разворачивать\эксплуатировать) с системой.
Первый тип документации — наши требования к системе. В эпоху LLM, кодогенерации и декларативного подхода к описанию инфраструктуры, мы будем вести требования так, чтобы система, там где это возможно, сама собиралась из них. Поэтому документация первого типа потребует высокого аудита качества. Ревью изменений, совместная работа, ведение версий, с возможностью отката, автоматическая сборка. Все то, что присуще подходу Docs as Code.
Второй тип документации — описание текущего состояния системы. Так как мы не хотим разрыва между описанием системы и самой системой, мы будем пытаться генерировать человеко-читаемое описание из кода и конфигурации. Назовем этот подход Code as Docs.
Третий тип — различные виды пользовательской документации. Эту форму документации мы постараемся минимизировать, сделав понятным наши интерфейсы и встроив подсказки прямо в процесс работы пользователя с системой. Назовем это подходом No Docs.
На этом можно было бы и закончить, но пройдемся подробнее по каждому пункту.
Современные инструменты успешно превращают текстовое описание в наглядные диаграммы, включая профессиональные нотации, например, BPMN.
Такие инструменты, как Miro AI, Whimsical и Eraser.io, превращают текстовое ТЗ в аккуратные и настраиваемые схемы за считанные секунды. ChatGPT выступает в роли универсального аналитика, который может и написать код для диаграммы, и детально её описать. А для задач профессионального моделирования уже существуют специализированные решения вроде Bonita AI BPMN Generator.
В этой статье мы разберем, как ИИ-помощники справляются с генерацией диаграмм, в чем их сильные стороны и как с их помощью за минуты превратить текстовое описание в готовую схему.
Также рассмотрим ИИ, как практический инструмент для структурирования, декомпозиции и визуализации размытых требований.
Одной из важнейших задач при проектировании высокочастотных и высокоскоростных цифровых схем является борьба с паразитными ёмкостями на печатной плате.
Паразитная ёмкость на печатной плате — это непреднамеренная ёмкость, которая возникает между проводящими частями печатной платы, разделёнными изолирующим материалом. Это может относиться к ёмкости между дорожками, выводами, компонентами или между дорожкой и плоскостью заземления. Паразитная емкость препятствует работе схемы, может вызывать перекрёстные наводки, задержки сигналов, искажения фронтов и даже нестабильность работы схемы.
Вечные переделки и продукты, не решающие реальные проблемы? Возможно, вашей команде не хватает фазы Discovery.
Из этой статьи вы узнаете, как внедрить фреймворк, который делит работу на две четкие стадии: Исследование (Discovery) и Реализация (Delivery).
На практическом примере разберем:
- Как провести глубинное исследование проблемы до написания первой строчки кода.
- Что входит в процессы бизнес- и системного анализа на каждом этапе.
- Шаги внедрения фреймворка на вашем проекте.
Перестаньте тушить пожары и начните создавать востребованные продукты.