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

Привет, Хабр! Давайте знакомиться! Меня зовут Дима. Я много лет работаю системным аналитиком.

За моими плечами – десятки проектов по разработке и внедрению программного обеспечения, где я не только проектировал, но и проводил ревью процессов других аналитиков и специалистов заказчика. Кроме того, регулярно проводил обучение по нотации 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).

На практическом примере разберем:

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

Перестаньте тушить пожары и начните создавать востребованные продукты.

Делая проект, разработчик не всегда понимает, что толщина стеклотекстолита не равна финальной толщине печатной платы. В этой статье мы решили разъяснить из чего формируется финальная толщина печатной платы и как правильно ее рассчитать.

Финальная толщина печатной платы формируется из нескольких основных компонентов.

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

Отдел технического контроля (ОТК) играет ключевую роль в производстве печатных плат так как даже незначительные дефекты могут привести к отказу электронных устройств. ОТК на производстве гарантирует качество, надежность и соответствие продукции требованиям стандарта ГОСТ. В этой статье делимся, как это происходит у нас, в «ЭЛЕКТРОконнект». Мы со всей ответственностью относиться к качеству продукции и постоянно совершенствуется.

Каким образом организован процесс технического контроля на производстве «ЭЛЕКТРОконнект»?

В процессе производства на заводе осуществляются 3 этапа проверки качества печатных плат:

• Автоматическая оптическая инспекция (AOI).

• Электроконтроль на тестерах с летающими щупами (FPT).

• Визуальный ручной контроль (MVI).

Автоматизированный оптический контроль (AOI) 

Задача этой статьи предоставить Вам сухие факты о двух материалах, которые мы используем в своем производстве. Понимая характеристики и сопоставляя их с требованиями Вашего проекта выбор будет сделать проще.

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

Гибкие печатные платы (FPC, Flexible Printed Circuits) на основе полиимида и FR4 толщиной 0.1 - 0.2 мм используются в компактных и высоконадежных электронных устройствах. Рассмотрим их особенности, сравнение и применение.

Но помимо полиимида, есть также материал FR4, который также тонок, но значительно дешевле?

О сильных и слабых сторонах 2х материалов ниже.

Первое, что нужно знать о гибко-жестких печатных платах (ГЖПП) — это дорого. И использовать рекомендуется в технически обоснованных случаях.

Иногда ГЖПП можно заменить просто гибкими (многократно гибкими) или тонкими (0,1 мм) стеклотекстолитовыми (гибкими однократно). Главные положительные свойства гибко-жестких печатных плат — уменьшение габаритных размеров и массы, повышение надежности изделия за счет исключения промежуточных разъёмов и в части вибростойкости. В частности, возможны фантастические пространственные конструкции по сравнению с обычными платами.

Коротко о конструкции гибко-жестких печатных плат. На нашем производстве используются следующие варианты: Две (или более) двусторонние «жесткие» платы из стеклотекстолита и между ними размещается двухсторонняя «гибкая» полиимидная плата (шлейф) толщиной 0,05 мм с проводящим рисунком, спрессованная в жесткой части «малотекучим» препрегом. Над гибкой частью препрег удаляется. Рисунок (проводники) гибкой части обычно покрываются «покровной пленкой» для предотвращения замыканий и для защиты проводников от внешних факторов. Проводники должны размещаться на наружных слоях платы и как минимум на одном гибком слое. Можно изготовить платы и с несколькими гибкими полиимидными слоями. Полиимидный гибкий слой является общим объединяющим элементом ГЖПП.

«Гибкость» (радиус изгиба) всей конструкции полностью определяется толщиной и количеством меди на гибких слоях. Сам полиимид можно согнуть радиусом около 1 мм. Вспомните ленту катушечного или кассетного магнитофона. Наименьший радиус будет у односторонней платы с тонкими проводниками, наибольший у двухсторонних полигонов на всю ширину. Покровная пленка также увеличивает радиус сгибания платы. Если гибких слоёв больше двух — аналогично.

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

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

Привет, Хабр! На связи Маргарита Сорочинская, технический писатель отдела архитектуры в Рунити. Хочу рассказать, как мы в компании подошли к описанию API в Swagger — и почему решили перенести туда всё, что раньше жило в Confluence. А еще поделюсь с вами стартерпаком для описания API в Swagger, пошаговой инструкцией и всеми ссылками, чтобы для вас этот путь был уже более простым.

Добрый день, дорогие читатели!

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

Как вы думаете, сколько человек документирует продукты в Postgres Professional? 50? 100? А вот и нет — всего десять. Рассказываем, как команде техписателей удается управлять сотнями файлов, почему их работа — это квест, и как они успевают контрибьютить в ванильный PostgreSQL.

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

Вряд ли найдётся кто-либо, кто в здравом уме и ясной памяти будет отрицать необходимость документации. Любой продукт имеет (или должен иметь) свою документацию. Как минимум – инструкцию о том, как этим продуктом пользоваться. Производители почти всегда указывают – «прежде чем начать пользоваться нашим продуктом, внимательно ознакомьтесь с инструкцией».  

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

Но ЧТО же должен создавать автор документации? Что должна в себя включать документация, когда, на каком этапе и в каком объёме она должна создаваться, ЧТО она должна содержать, когда, кому и при каких обстоятельствах она может потребоваться?

В данной статье мы и поразмышляем об этом...

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