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

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

Почему общение становится такой проблемой? Потому что его слишком много, оно хаотично и не имеет единого центра. Вас дергают коллеги, сыплются непонятные задачи, начальство ставит задания вскользь на созвонах, а через месяц интересуется результатом. Информация теряется в почте, чатах и в собственной памяти. А ещё фоном мозг напоминает: "Не забудь, надо сделать то-то и то-то!".

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

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

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

История направления NSR Specification началась в далеком 2021 году, когда мы выпустили Модуль требований — базу знаний по стандартам для строительства и смогли реализовать первую связь с САПР nanoCAD в виде панели подсказок нормативных требований. Для автоматизации разработки и актуализации базы мы реализовали первый инструмент, использующий ИИ-компоненты:  Модуль семантической разметки документа, с функциями выделения границ требований и привязки кодов КСИ. Следом, мы разработали свой текстовый редактор, специально для создания текстов стандартов, организации процесса публичного обсуждения и публикации отдельных требований в базу Модуля требований.  

Но это было только начало. Наша главная цель, ради которой и стартовала работа направления NSR Specification: автоматизация оценки соответствия ЦИМ — требованиям стандартов.

О процессе разработки NSR Модуль семантического анализа «как на духу» мы рассказали вот здесь. Пилотные проекты с гигантами рынка, предоставившими нам свои информационные модели, помогли нам сделать продукт работоспособным. Подробнее об этом можно почитать тут.

Последний модуль, NSR Модуль семантического поиска, родился, когда нам отчаянно захотелось попробовать реализовать RAG-пайплайн. Год разработки, и простой RAG стал продвинутым,  векторный поиск был заменён на гибридный, были усовершенствованы и модифицированы компоненты парсинга и чанкинга текстов, векторизована метаинформация нормативных требований (для привязки к контексту), реализован режим диалога, подобраны шаблоны промптов для лучшего анализа нормативных и технических текстов.

Приветствую всех! С вами старший системный аналитик, эксперт онлайн-школы по системному анализу Ольги Пономарёвой System Analyst. Статья основана на практическом опыте, в нашей школе мы не просто даем теорию, а любим делиться тем, что действительно работает на проектах.

Разбор legacy-системы без документации кажется сложной задачей. Но это возможно с правильным подходом и современными инструментами. Это руководство даст вам план действий, практические методы и покажет, как использовать ИИ для ускорения работы.

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

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

В статье расскажу о пяти важных блоках информации, которые обязательно должно содержать руководство пользователя (оно же User Guide).

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

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

База знаний помогает пользователям быстро понять, какие возможности есть у облачных сервисов — так же, как качественный README объясняет назначение open source‑проекта. 

В этом материале мы собрали несколько интересных бесплатных инструментов для подготовки README.

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

НИИ ПТЭС — один из лидеров российского строительного рынка — как и многие отечественные предприятия столкнулся с необходимостью импортозамещения. Маркетолог компании Евгений Платонов рассказывает, почему инженеры выбрали именно nanoCAD и как был организован путь от тестового периода до успешного внедрения новой САПР в бизнес-процессы.

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

В статье пытаемся разобраться какой ключевой навык аналитика и как его можно проверять на собеседовании...

Приглашаем на премьеру TDMS Фарватер Web — новой системы с удобным веб‑интерфейсом для документооборота и управления проектированием в строительстве.

Дата и формат: 30 сентября в 11:00 (МСК), онлайн, бесплатно

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

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

Мы — команда документирования платформы Platform V в СберТехе: Лидия Ковач, middle технический писатель, Мария Бурханова, senior технический писатель, и Светлана Каюшина, руководитель команды. Хотим рассказать, как мы разработали глоссарий, который повысил качество документации нашей цифровой платформы для построения ИТ‑ландшафта.

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

Сегодня расскажем, как инженеры центра «ПрофИнформЗащита» внедрили nanoCAD BIM ОПС и смогли существенно сократить сроки подготовки проектной документации на примере реальных кейсов.

Всем привет, меня зовут Максим, я QA-специалист в компании SimbirSoft. Более двух лет я занимаюсь обеспечением качества, за это время мне часто попадались проекты с отсутствующей или устаревшей технической документацией. Как быть в подобной ситуации и при этом сохранить нервные клетки, я расскажу в этой статье.
Бывают ситуации, когда тестировать приходится вопреки. Вопреки срокам, здравому смыслу или отсутствию требований. Именно последний кейс мы и разберем с вами сегодня 🦾

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

В результате то, на что enterprise-команды тратят месяц (на подготовку полного пакета требований на 60-100 страниц), задействуя несколько специалистов, «Кентавр» делает за пару дней силами одного аналитика. При этом документы качественнее: структурированные, непротиворечивые и главное — повторяемые от проекта к проекту.

О том, как создавалась эта система, с какими проблемами столкнулись разработчики и почему простого ChatGPT недостаточно для серьезной документации, рассказали Андрей Шагалов, директор по маркетингу Artezio, и Денис Харченко, директор по развитию бизнеса компании. Они поделились техническими деталями архитектуры, объяснили концепцию Human-in-the-Loop и раскрыли планы по превращению нового инструмента в популярный коммерческий продукт.

Технический писатель — своего рода проводник между разработчиками и пользователями. Мы берём техзадания, обрывочные комментарии, макеты, проходим процессы в продукте и создаем понятные инструкции. Часто на стадии подготовки возникают вопросы: «Где искать информацию — и какую?»

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

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

В предыдущей статье мы рассмотрели, как система Документы способствует выстраиванию процесса управления документацией в административно-хозяйственном отделе (АХО). На этот раз мы рассмотрим отдел кадров.

Это короткий пост, вдохновлённый карточками по теме, которые я встретил на канале S0ER'а. В геймдеве такая практика встречается нечасто. Поэтому внесу дополнительное упоминание в ленту. Оставлю вводные, ссылки на более подробное изучение, поделюсь своим опытом и расскажу, какое отношение к этому имеет AI.

Привет, Хабр! Меня зовут Мария Бурханова, я технический писатель, старший руководитель ИТ-направления документирования Platform V в СберТехе. На TechWriter Days я рассказывала, как техническому писателю научиться читать и понимать сложные нотации, чтобы сделать документацию простой и понятной.

Сегодня хочу рассказать, зачем техпису нужны нотации и почему их так много, какие знания о нотациях точно пригодятся и как применить эти знания на практике.

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