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

Недавно к нам в компанию взяли нового сотрудника на должность программист или разработчик MS Dynamics AX 2012 (для начала выбрали версию 2012, но с перспективой его быстрого переключения на любые версии, включая D365 FO) — стажёр Воякс Иван Иванович (он же Woyax).

Формат DITA позволяет полностью сосредоточиться на содержании документа и не думать о его оформлении. Кроме того, этот инструмент помогает легко и быстро вносить изменения и дополнения в уже написанные ранее документы. Если с DITA как следует разобраться, то потом написание сложных технических документов существенно упростится.

В этой статье я расскажу об основных достоинствах DITA.

Борьба с последствиями плохого ТЗ иногда ценится выше, чем работа по его предотвращению.

Кратко о парадоксе: все ругают костыли и авралы, но они повторяются вновь и вновь. Значит, это кому-то нужно? Посмотрим на экосистему проекта не с технической, а с экономической и карьерной точек зрения.

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

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

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

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

Документация может спасти проект или убить его, если подойти к ней без дисциплины

В этой статье системный аналитик Влад показывает, как применять инженерные принципы — 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 так хвалят во всех статьях, и он используется всеми специалистами, значит проблема во мне и моих профессиональных способностях?!». В этой и следующих статьях по проектированию процессов я постараюсь развеять эти сомнения, чтобы у аналитиков, попавших в такую ситуацию, было больше шансов сохранить веру в себя, не выгореть и успешно завершить проект.

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