TechWriter Days 3. Как это было

 

27-28 марта в Москве прошла 3-я конференция для технических писателей — TechWriter Days 3.

Сайт конференции — https://techwriterdays.ru/.

Программа — https://techwriterdays.ru/ru/program/137253

«Я там был, мед, пиво пил» © И хочу поделиться с вами. Конференция отпочковалась от конференции аналитиков, так как тех писы уже — дело стандартное, есть отдельные должности под них.

А я сама в свое время и аналитиком на проектах была, да и с документацией работала постоянно, потому что я — бюрократ ))) Так что очень интересно было посетить эту конференцию.

Организация тут, как всегда у Владислава с Татьяной Орликовых, на высоте. Еда, чай, место для отдыха, куча всяких активностей, да и просто интересные доклады! Расскажу про те, где я была и где хотела бы.

Мой список "посмотреть потом"

1. Тихая эпидемия в IT, или Почему выгорают технические писатели — плохо себя чуствовала, не осталась на последние доклады, ушла домой. Но исходно ставила галочку сходить на доклад. Полистала слайды — интересно и жизненно, особенно про команды, где твою роль не понимают. Хотя это история про выгорание, а хотелось бы "что делать в такой команде", но тоже интересно)
2. Использование стилей MS Word без страха — тут обещают реальные кейсы из жизни, я такое люблю)
3. Внутреннее продвижение базы знаний: от справочника до культуры работы с информацией — внутреннее продвижение тоже очень актуальная тема!
4. Документация как продукт: от текстов к стратегии и управлению опытом — документация как отдельный продукт, в том числе улучшаюший онбординг. Это прям откликает мне, я сама делала онбординг))
5. Отчеты и метрики в документации: как считать влияние на бизнес — всегда интересно, кому какие метрики зашли

Какие доклады я слушала

Кому доверить ревью API — техпису или искусственному интеллекту. Камила Мазаева

Ссылка на доклад

Камила работает в Альфабанке, где много всяких разных проектов. Путь документации там такой:

Аналитик → техпис → разработка

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

Поэтому решили нудную работу делегировать ИИ. Посмотрели, что да как, и решили сделать так, чтобы ИИ не вносил правки в текст, а присылал отчет по найденным проблемам:

• уровень критичности
• где проблема?
• как написать лучше

И человек уже принимает или отклоняет такие правки. В итоге аналитик открывает чат с ботом, куда уже внесен нужный промт → дал документацию, получил фидбек. Красота!

Ну и выводы — ИИ хорошо правит простые опечатки и быстро обрабатывает документы. Но не очень хорош с контекстом, терминологией и работе с неоднозначностью.

И, конечно, нужно помнить, что сердце ИИ — хороший промт!

Через тернии к звездам: как мы перевезли всю документацию Яндекса на Diplodoc. Эльвира Гильманова и Михаил Кошкин

Ссылка на доклад

Довольно интересный рассказ о переезде документации с одной платформы на другую. Переезд занял 5 лет! 😶

Раньше жили на DITA, которая выглядела как документация из 2000-х годов, перешли на YFM.

Всякое бывало, что-то предусмотрели, а что-то — нет.

Были и косяки — нужно было объединить документацию. Посмотрели, она написана на разных платформах, провели диагностику, какая лучше, выбрали... DITA. И через месяц узнали, что все пеередут в YFM.

Была ситуация со старым багом, который вроде как не очень хорошо ловится, вот и не правили. А потом выяснилось, что популярная документация не могла из-за него мигрироваться. Пытались сделать костыли — заняло квартал с нулевым результатом. А переписать с нуля заняло месяц.

Так что хоть "переписать с нуля" и боятся, иногда это самый лучший вариант. И даже самый быстрый, хотя кажется наоборот))

Собрать документацию в один клик: опыт применения языковых моделей и шаблонизаторов. Никита Осокин

Ссылка на доклад

Ребята работают по ГОСТ — а это часто не про «написать документацию», а про коммуникации, про «правильную» структуру документа.

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

В итоге раньше переименовали какое-то название — это надо открыть ворд, ctrl + f, поиск, замена... А если разные падежи, оно ещё и не работает! Что сделали? Единый банк переменных.

Ну и не только его, конечно)) В итоге что получили? Приходит заказчик:

— Ой, а давайте всё же систему именовать не АС "Документирование", а АС "Техпис"

Раньше такие просьбы за неделю до сдачи проекта вызывали желание выйти в окно, а теперь "да легко"

Масштаб, сложность, автоматизация: как агенты изменили процесс документирования в Yandex Cloud. Александр Яковлев

Ссылка на доклад

Александр рассказал про их опыт внедрения ИИ. Какие инструменты использовали:

Методом проб и ошибок пришли к таким выводам:

• агент не работает с гитом, не пушит сам — иначе он такого напушит, что только всё испортит
• тестирование документации тоже на людях — ИИ бы справился, но это хорошее время для ревью.

Что входит в настройку агента:

• системный промт
• режим
• фоновые знания

Где в итоге агент может реально приносить пользу?

1. Создание структурированной информации — пошаговые инструкции, обзорные статьи
2. Обновление существующей документации на основе тикетов, скринов, истории изменений
3. Подготовка Release Notes
4. Анализ актуальности документации из истории изменений и релизов инструментов.

Был кейс — уволился человек, который отвечал за несколько проектов. Попросили ИИ проанализировать документацию на основании как раз таки истории изменений. Да, это заняло 1.5 млн токенов, но был вау-результат и найдено много проблем в доке.

Changelog на лету: автоматическая генерация с помощью GitLab. Татьяна Кириллова

Ссылка на доклад

В чем разница между RN и CL?

• Release Notes — документация для пользователей
• Changelog — для разработчиков, что вообще и где менялось.

Так вот. Схема до автоматизации, техпис собирает change log сам:

Неприкольно! И трудозатратно. Поэтому описали критерии "что хотим от автоматизации", погуглили инструменты и сравнили по своим критериям:

Простой подход, но зато выбор становится очевиден!

НО! Возникла проблема — робот не человек, ему нужен шаблон. И надо вводить соглашение о коммитах, иначе все пишут как душе угодно, и собранный ченджлог будет просто нечитаем. А это надо убедить разработчиков писать "как положено" )))

В итоге:

• пока проводят ревизию сообщений
• планируют прикрутить автоматическое соглашение

Ну и закрепили структуру сообщения:

• Номер задачи — обязательно
• Тип — fix, new...
• Описание 
• Тело (необязательное)

Пока обкатывают, впереди ещё долгий путь)

Матрица зрелости процессов работы с текстом в ИТ. Анна Терновая

Ссылка на доклад

Зачем вообще нужна матрица зрелости? Есть несколько разных причин:

Анна рассказала про то:

• Какую литературу использовали при изучении темы
• Какую матрицу выбрали себе

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

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

Так что нужно заручиться поддержкой одной из команд, а потом история успеха будет продвигать вас сама =)

Подготовка к документированию: читаем ТЗ, собираем информацию. Софья Новикова

Ссылка на доклад

Софья рассказывала, как собирать информацию из разных источников:

А ещё, если документация разбита на разделы, техписы вычитывают каждый раздел — всё ли понятно? А если нет, термины можно сначала погуглить или спросить у ИИ, чтобы не отвлекать коллег лишний раз вопросами!

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

Документация как зеркало продукта: роль технических писателей в улучшении пользовательского опыта. Эльвира Дёгтева

Ссылка на доклад

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

Кейсы из жизни — это всегда интересно. И тут как раз кейсы из серии "пройти мимо, сделав вид, что всё ок, не моя же зона ответственности", или начать копать... И копать... И копать))) Интересные истории!

Трансфер знаний от уходящих сотрудников. Denis Mazin

Ссылка на доклад

Тут интересная история — каким-то образом ребята выявили, что 18% сотрудников в зоне риска ухода. И надо бы передать их знания, пока они не пропали...

Накидали такую матрицу:

Запланировали передачу знаний и понеслось... Сначала сотрудникам некогда этим заниматься. Благо начальство поддержало и поставило высокий приоритет задаче. Но всё равно работу тоже надо работать.

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

Матрица итеративного редактирования. Анна Штольц 

Ссылка на доклад

Редакторы постоянно сталкиваются со сжатыми сроками. Дают текст на 250 стр и говорят, что есть полчаса. Что делать?

В идеале нулевым этапом надо текст просто прочитать — тогда поймешь, хватит времени или надо сразу просить сроки увеличить.

Ну а потом идет итеративное вычитывание, потому что так проще, если держать в уме сразу всё, что-то обязательно пропустишь. Да и не всегда нужна полная и подробная вычитка.

Выделили такие этапы:

1. Корректура — почти на автомате, всякие опечатки (странно, что не передали это ИИ)
2. Литературная правка
3. Выравнивание стиля — много жаргона? Это плохо.
4. Фактчекинг — названия, имена, даты, логика повествования
5. Отделка

Интересно было посмотреть со стороны, как преображается текст, так как Анна показывала все на конкретном примере, а в итоге «до — после». 

Уровни качества документирования. Оксана Гаврюшенко

Ссылка на доклад

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

Так что ребята сделали разную градацию — что нужно? Одноразовая работа? Чтобы документация потом жила? Должна ли соответствовать ГОСТ? И прочее. Всё это влияет на сроки и стоимость. И главное, что надо научиться понимать — разницу между желаемым и достаточным.

Ну а в докладе Оксана приводит примеры своих матриц влияния результата на стоимость. Вполне любопытно посмотреть на чужой подход)

Декомпозиция страха: практики взаимопонимания для руководителей и команд техписателей. Мария Макеева

Ссылка на доклад

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

Мне стало интересно послушать такой доклад, вот я сюда и завернула. А это доклад про то, как вырасти в руководителя был =))) Но тоже неплохой, как стать хорошим руководителем, а не просто начальником с кнутом!

Орг вопросы

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

Помимо обеда — всякие ништяки в кофе зоне. Причем с утра и после обеда это что-то мясное / рыбное. Бутербродики, например. Чтобы можно было перекусить, если пропустил завтрак или приехал на конференцию прям с поезда. Очень здорово сделано 💖

Плюс комната для отдыха с аэрохоккеем, VR-очками и даже игровым автоматом))) 

А ещё куча разных стендов, где тоже и розыгрыши есть, и пообщаться с докладчиками можно. А ещё туда издательство Питер приезжает и книги продает, дешевле, чем в магазине. Я там прибарахлилась немношко)) Жаль, что серию Head First O`Really они больше не возят, я бы из неё пару книг тоже взяла...

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

Резюме

Конференция — это всегда место вдохновления. И место встреч! Когда ещё вы сможете встретиться с коллегами, живущими в других городах?)))

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

Буду теперь ждать TechWriter Days 4 =)