Обновить
35.39

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

Всё о деятельности технических писателей

Сначала показывать
Порог рейтинга
Уровень сложности

Мой лог — моя крепость: Как один файл наводит порядок в работе

Уровень сложностиПростой
Время на прочтение10 мин
Количество просмотров4.7K

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

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

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

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

Логи, логи... При чём тут логи???

«Нанософт» сказал — «Нанософт» сделал. Представляем новые ИИ-модули NSR Specification для инженеров и проектировщиков

Время на прочтение3 мин
Количество просмотров590

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

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

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

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

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

Подробнее о функционале платформы

Как аналитику разобраться в legacy-системе без документации

Уровень сложностиПростой
Время на прочтение6 мин
Количество просмотров1.1K

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

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

Читать далее

User guide — пустая формальность или незаменимый документ? Руководство, как написать руководство

Время на прочтение6 мин
Количество просмотров2.8K

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

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

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

Читать далее

Как сделать сложный технический текст простым и понятным: приемы из практики технического писателя

Уровень сложностиПростой
Время на прочтение3 мин
Количество просмотров3.1K

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

Читать далее

Альтернативная нотация описания архитектуры ИТ систем

Уровень сложностиСредний
Время на прочтение4 мин
Количество просмотров4.8K

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

Читать далее

Полезный проект — ещё полдела: инструменты для оформления README и документации

Уровень сложностиПростой
Время на прочтение4 мин
Количество просмотров5.2K

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

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

Читать далее

Купить квартиру в Дубае: ТОП-5 проверенных  агентств недвижимости для покупки жилья в Эмиратах

Уровень сложностиСложный
Время на прочтение6 мин
Количество просмотров3K

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

Читать далее

Битва САПР. Как НИИ ПТЭС выбрал nanoCAD и прокачал портфель проектных услуг

Время на прочтение3 мин
Количество просмотров3.9K

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

Читать далее

Какие требования могут предъявить на джуниора системного аналитика?

Время на прочтение10 мин
Количество просмотров854

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

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

Читать далее

TDMS Фарватер Web: смотрите онлайн-премьеру 30 сентября

Время на прочтение2 мин
Количество просмотров203

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

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

Читать далее

Система документации для проектного офиса: создаем живую модель, а не очередную бюрократию

Уровень сложностиСредний
Время на прочтение8 мин
Количество просмотров3.8K

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

Читать далее

Как мы составляем глоссарий для сложной технологической платформы

Уровень сложностиПростой
Время на прочтение9 мин
Количество просмотров1.2K

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

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

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

Читать далее

Ближайшие события

Кейс: как nanoCAD BIM ОПС помогает автоматизировать пожарную безопасность и противодымную защиту

Время на прочтение2 мин
Количество просмотров500

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

Читать далее

Тестирование в условиях отсутствия технической документации

Уровень сложностиСредний
Время на прочтение8 мин
Количество просмотров1.4K

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

Читать далее 👇

«Кентавр» против хаоса документации: как Artezio научила ИИ писать техзадания в 10 раз быстрее

Уровень сложностиПростой
Время на прочтение12 мин
Количество просмотров1.6K

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

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

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

Читать далее

Как метод из аниме Mononoke помогает техническому писателю найти информацию

Уровень сложностиПростой
Время на прочтение7 мин
Количество просмотров9.2K

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

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

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

Читать далее

Как система Документы помогает документообороту в отделе кадров

Уровень сложностиПростой
Время на прочтение6 мин
Количество просмотров767

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

Читать далее

ADR: фиксируем архитектурные решения

Уровень сложностиПростой
Время на прочтение2 мин
Количество просмотров1.7K

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

Читать далее

Как техпису общаться с командой разработки на одном языке (нотаций), или Учимся приручать лису

Уровень сложностиПростой
Время на прочтение11 мин
Количество просмотров2K

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

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

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

Читать далее