27-28 марта в Москве прошла 3-я конференция для технических писателей — TechWriter Days 3.
Сайт конференции — https://techwriterdays.ru/.
Программа — https://techwriterdays.ru/ru/program/137253
«Я там был, мед, пиво пил» © И хочу поделиться с вами. Конференция отпочковалась от конференции аналитиков, так как тех писы уже — дело стандартное, есть отдельные должности под них.
А я сама в свое время и аналитиком на проектах была, да и с документацией работала постоянно, потому что я — бюрократ ))) Так что очень интересно было посетить эту конференцию.
Организация тут, как всегда у Владислава с Татьяной Орликовых, на высоте. Еда, чай, место для отдыха, куча всяких активностей, да и просто интересные доклады! Расскажу про те, где я была и где хотела бы.
Мой список "посмотреть потом"
- Тихая эпидемия в IT, или Почему выгорают технические писатели — плохо себя чуствовала, не осталась на последние доклады, ушла домой. Но исходно ставила галочку сходить на доклад. Полистала слайды — интересно и жизненно, особенно про команды, где твою роль не понимают. Хотя это история про выгорание, а хотелось бы "что делать в такой команде", но тоже интересно)
- Использование стилей MS Word без страха — тут обещают реальные кейсы из жизни, я такое люблю)
- Внутреннее продвижение базы знаний: от справочника до культуры работы с информацией — внутреннее продвижение тоже очень актуальная тема!
- Документация как продукт: от текстов к стратегии и управлению опытом — документация как отдельный продукт, в том числе улучшаюший онбординг. Это прям откликает мне, я сама делала онбординг))
- Отчеты и метрики в документации: как считать влияние на бизнес — всегда интересно, кому какие метрики зашли
Какие доклады я слушала
Кому доверить ревью API — техпису или искусственному интеллекту. Камила Мазаева
Камила работает в Альфабанке, где много всяких разных проектов. Путь документации там такой:
Аналитик → техпис → разработка
Технический писатель нужен, потому что документацию пишут разные люди, в разных стилях. А нужен единый, за этим следит техпис. Но техписы тонут в работе — когда приходят документы с опечатками, разным стилем и тд.
Поэтому решили нудную работу делегировать ИИ. Посмотрели, что да как, и решили сделать так, чтобы ИИ не вносил правки в текст, а присылал отчет по найденным проблемам:
- уровень критичности
- где проблема?
- как написать лучше
И человек уже принимает или отклоняет такие правки. В итоге аналитик открывает чат с ботом, куда уже внесен нужный промт → дал документацию, получил фидбек. Красота!
Ну и выводы — ИИ хорошо правит простые опечатки и быстро обрабатывает документы. Но не очень хорош с контекстом, терминологией и работе с неоднозначностью.
И, конечно, нужно помнить, что сердце ИИ — хороший промт!
Через тернии к звездам: как мы перевезли всю документацию Яндекса на Diplodoc. Эльвира Гильманова и Михаил Кошкин
Довольно интересный рассказ о переезде документации с одной платформы на другую. Переезд занял 5 лет! 😶
Раньше жили на DITA, которая выглядела как документация из 2000-х годов, перешли на YFM.
Всякое бывало, что-то предусмотрели, а что-то — нет.
Были и косяки — нужно было объединить документацию. Посмотрели, она написана на разных платформах, провели диагностику, какая лучше, выбрали... DITA. И через месяц узнали, что все пеередут в YFM.
Была ситуация со старым багом, который вроде как не очень хорошо ловится, вот и не правили. А потом выяснилось, что популярная документация не могла из-за него мигрироваться. Пытались сделать костыли — заняло квартал с нулевым результатом. А переписать с нуля заняло месяц.
Так что хоть "переписать с нуля" и боятся, иногда это самый лучший вариант. И даже самый быстрый, хотя кажется наоборот))
Собрать документацию в один клик: опыт применения языковых моделей и шаблонизаторов. Никита Осокин
Ребята работают по ГОСТ — а это часто не про «написать документацию», а про коммуникации, про «правильную» структуру документа.
И вот мучались, мучались, и решили сделать свое решение. Да, оно в маркдауне и после ворда писать бывает сложновато, но тут у них ИИ, наученный помогать и подсказывать, как что-то сделать.
В итоге раньше переименовали какое-то название — это надо открыть ворд, ctrl + f, поиск, замена... А если разные падежи, оно ещё и не работает! Что сделали? Единый банк переменных.
Ну и не только его, конечно)) В итоге что получили? Приходит заказчик:
— Ой, а давайте всё же систему именовать не АС "Документирование", а АС "Техпис"
Раньше такие просьбы за неделю до сдачи проекта вызывали желание выйти в окно, а теперь "да легко"
Масштаб, сложность, автоматизация: как агенты изменили процесс документирования в Yandex Cloud. Александр Яковлев
Александр рассказал про их опыт внедрения ИИ. Какие инструменты использовали:
Методом проб и ошибок пришли к таким выводам:
- агент не работает с гитом, не пушит сам — иначе он такого напушит, что только всё испортит
- тестирование документации тоже на людях — ИИ бы справился, но это хорошее время для ревью.
Что входит в настройку агента:
- системный промт
- режим
- фоновые знания
Где в итоге агент может реально приносить пользу?
- Создание структурированной информации — пошаговые инструкции, обзорные статьи
- Обновление существующей документации на основе тикетов, скринов, истории изменений
- Подготовка Release Notes
- Анализ актуальности документации из истории изменений и релизов инструментов.
Был кейс — уволился человек, который отвечал за несколько проектов. Попросили ИИ проанализировать документацию на основании как раз таки истории изменений. Да, это заняло 1.5 млн токенов, но был вау-результат и найдено много проблем в доке.
Changelog на лету: автоматическая генерация с помощью GitLab. Татьяна Кириллова
В чем разница между RN и CL?
- Release Notes — документация для пользователей
- Changelog — для разработчиков, что вообще и где менялось.
Так вот. Схема до автоматизации, техпис собирает change log сам:
Неприкольно! И трудозатратно. Поэтому описали критерии "что хотим от автоматизации", погуглили инструменты и сравнили по своим критериям:
Простой подход, но зато выбор становится очевиден!
НО! Возникла проблема — робот не человек, ему нужен шаблон. И надо вводить соглашение о коммитах, иначе все пишут как душе угодно, и собранный ченджлог будет просто нечитаем. А это надо убедить разработчиков писать "как положено" )))
В итоге:
- пока проводят ревизию сообщений
- планируют прикрутить автоматическое соглашение
Ну и закрепили структуру сообщения:
- Номер задачи — обязательно
- Тип — fix, new...
- Описание
- Тело (необязательное)
Пока обкатывают, впереди ещё долгий путь)
Матрица зрелости процессов работы с текстом в ИТ. Анна Терновая
Зачем вообще нужна матрица зрелости? Есть несколько разных причин:
Анна рассказала про то:
- Какую литературу использовали при изучении темы
- Какую матрицу выбрали себе
Главная фишка — делить каждую колонку на "наших и ваших", команду разработки и команду документирования. Потому что уровни зрелости могут быть разные и повлиять на чужую команду вы можете не всегда.
Ну а дальше смотрим на примерах, как могут выглядеть эти матрицы и что с этим делать. Когда уже есть внедренное решение, всегда можно показать "незрелой" команде пользу — смотрите, вот мы выросли в матрице и какие это профиты дало!
Так что нужно заручиться поддержкой одной из команд, а потом история успеха будет продвигать вас сама =)
Подготовка к документированию: читаем ТЗ, собираем информацию. Софья Новикова
Софья рассказывала, как собирать информацию из разных источников:
А ещё, если документация разбита на разделы, техписы вычитывают каждый раздел — всё ли понятно? А если нет, термины можно сначала погуглить или спросить у ИИ, чтобы не отвлекать коллег лишний раз вопросами!
В общем, если информации у вас мало, учитесь её собирать из разных мест, в том числе у коллег. База? База, но о ней надо помнить.
Документация как зеркало продукта: роль технических писателей в улучшении пользовательского опыта. Эльвира Дёгтева
Эльвира рассказала кейсы из жизни, когда пытаешься сделать мелкую задачу, которая выливается в большой рефакторинг))
Кейсы из жизни — это всегда интересно. И тут как раз кейсы из серии "пройти мимо, сделав вид, что всё ок, не моя же зона ответственности", или начать копать... И копать... И копать))) Интересные истории!
Трансфер знаний от уходящих сотрудников. Denis Mazin
Тут интересная история — каким-то образом ребята выявили, что 18% сотрудников в зоне риска ухода. И надо бы передать их знания, пока они не пропали...
Накидали такую матрицу:
Запланировали передачу знаний и понеслось... Сначала сотрудникам некогда этим заниматься. Благо начальство поддержало и поставило высокий приоритет задаче. Но всё равно работу тоже надо работать.
В итоге за год сделали многое, и пришли к неожиданному выводу, что передача знаний — это не разовая акция, а постоянная. Уйти может любой, заболеть, а знания брать где? Так что ребята теперь работают над встраиванием этого процесса в основной.
Матрица итеративного редактирования. Анна Штольц
Редакторы постоянно сталкиваются со сжатыми сроками. Дают текст на 250 стр и говорят, что есть полчаса. Что делать?
В идеале нулевым этапом надо текст просто прочитать — тогда поймешь, хватит времени или надо сразу просить сроки увеличить.
Ну а потом идет итеративное вычитывание, потому что так проще, если держать в уме сразу всё, что-то обязательно пропустишь. Да и не всегда нужна полная и подробная вычитка.
Выделили такие этапы:
- Корректура — почти на автомате, всякие опечатки (странно, что не передали это ИИ)
- Литературная правка
- Выравнивание стиля — много жаргона? Это плохо.
- Фактчекинг — названия, имена, даты, логика повествования
- Отделка
Интересно было посмотреть со стороны, как преображается текст, так как Анна показывала все на конкретном примере, а в итоге «до — после».
Уровни качества документирования. Оксана Гаврюшенко
Оксана работает в компании, которая делает документацию на заказ. Поэтому каждый раз нужно отвечать заказчику на вопрос «почему так дорого».
Так что ребята сделали разную градацию — что нужно? Одноразовая работа? Чтобы документация потом жила? Должна ли соответствовать ГОСТ? И прочее. Всё это влияет на сроки и стоимость. И главное, что надо научиться понимать — разницу между желаемым и достаточным.
Ну а в докладе Оксана приводит примеры своих матриц влияния результата на стоимость. Вполне любопытно посмотреть на чужой подход)
Декомпозиция страха: практики взаимопонимания для руководителей и команд техписателей. Мария Макеева
Каюсь, на этот доклад я залетела случайно. Исходно собиралась в секцию B, но очень уж название зацепило. Прочитав название (не описание), я подумала, что там будет та же проблема, что звучала на конференции чуть ранее — когда другие отделы не понимают ценность техписов и надо ходить, доказывать её.
Мне стало интересно послушать такой доклад, вот я сюда и завернула. А это доклад про то, как вырасти в руководителя был =))) Но тоже неплохой, как стать хорошим руководителем, а не просто начальником с кнутом!
Орг вопросы
Место проведения — удобная гостиница, которая находится прямо около метро (что большой плюс). Места всем хватает, еды на обеде много всякой разной и вкусной.
Помимо обеда — всякие ништяки в кофе зоне. Причем с утра и после обеда это что-то мясное / рыбное. Бутербродики, например. Чтобы можно было перекусить, если пропустил завтрак или приехал на конференцию прям с поезда. Очень здорово сделано 💖
Плюс комната для отдыха с аэрохоккеем, VR-очками и даже игровым автоматом)))
А ещё куча разных стендов, где тоже и розыгрыши есть, и пообщаться с докладчиками можно. А ещё туда издательство Питер приезжает и книги продает, дешевле, чем в магазине. Я там прибарахлилась немношко)) Жаль, что серию Head First O`Really они больше не возят, я бы из неё пару книг тоже взяла...
Но в любом случае, заняться вам всегда будет чем. А ещё на конференции есть много людей, готовых вам помочь и ответить на все вопросы, так что по орг части никаких вопросов нет)
Резюме
Конференция — это всегда место вдохновления. И место встреч! Когда ещё вы сможете встретиться с коллегами, живущими в других городах?)))
Я рада, что конференция для технических писателей — это теперь отдельная конференция, для всех, кто любит документацию, кто тем или иным образом участвует в её создании. Документация — это очень важно! И здорово, что теперь есть, где поделиться своим опытом!
Буду теперь ждать TechWriter Days 4 =)
Комментариев нет:
Отправить комментарий