Таня Фокина, UX-писатель из ЦФТ, рассказывает о своей профессии и решает задачки в канале @rishavant.

С Таней мы давно знакомы, вместе работали в переводческой артели «Надмозг» и в ПК конференции DocFactor. Таня шарит, так что канал я очень рекомендую.

Мне особенно понравился пост про то, как полезно выяснять задачу бизнеса. У писателя по-хорошему не должно быть задачи «написать текст», как и у плотника нет задачи «поиспользовать молоток», а у хирурга «порезать скальпелем». Это всё инструменты, а не задачи.

https://t.me/rishavant/7

Мы тут поспорили, что канал @rishavant наберёт сотню за сутки. Осталось полчаса и 4 человека ;)

Писал это знакомой, которая хочет перейти в технические писатели. Но это верно для всех, кто в свои ХХ лет хочет поменять профессию и сомневается, что это можно сделать, не имея опыта.

Я в вас верю, вы сможете.

Екатерина Носкова из Xsolla рассказала про аналитику в документации. И не просто о сырых данных вроде количества просмотров, а о метриках, привязанных к реальной пользе для бизнеса. Это очень круто, читаю и восхищаюсь.

Xsolla — это платёжная система для игр и других приложений. Вот какие бизнес-метрики есть в доке Xsolla:

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

И внутренние метрики, показатели здоровья доки:
— Посещаемость по типу аудитории (b2b, b2c), языку и продукту. Просто суммарная посещаемость не имеет смысла, важны разрезы.
— Средняя скорость загрузки страниц. Это влияет сразу на UX и SEO.
— Индекс удовлетворённости пользователей — считается через форму фидбека 👍/👎.
— Качество документации, измеренное по нескольким показателям.
— Юзабилити документации — по анализу тепловых карт и записей сессий.

Читайте статью целиком, там много полезных идей. https://medium.com/xsolla-tech/analytics-in-documentation-d814bbbe6ea6

Подборка хороших сайтов с документацией, чтобы черпать вдохновение и красть, как художник: https://devportalawards.org/

С новым годом, друзья! :)

Писателям тоже будет полезно.

https://www.transposit.com/blog/2020.01.30-writing-runbook-documentation-when-youre-an-sre

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

Таня @rishavant запустила анонимный опрос о зарплатах UX-писателей. Если вы пишете интерфейсные тексты — пожалуйста, ответьте на пару вопросов. Результаты Таня потом опубликует.

https://forms.gle/gJD8Q9zVzmUP3Zbd9

Всем ГОСТописателям рекомендую слушать выпуск «Нового подкаста» про AsciiDoc и его использование в компании КУРС. Переходите уже к нам на светлую сторону, у нас docs-as-code и печеньки.

Ссылки на все платформы: https://newpodcast2.live/podcast/vanya-and-asiidoc/

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

А как же уважение и забота о людях? Без этого зачем вообще нужна редактура, все эти тексты?

Люди ведь важнее, чем слова.

С декабря прошлого года я руковожу командой технических писателей в tarantool.io. Это новый для меня продукт, новая роль и гора новых задач. Тематика канала теперь тоже расширится. В 2021 году ждите постов про:

— документацию как продукт;
— профессиональный рост писателя;
— руководство командой писателей;
— место и роль документации в технических коммуникациях, управлении знаниями и developer relations;
— и вакансии в @docops_jobs, наконец-то!

Документация как код, мероприятия и другие хорошие штуки тоже останутся. Надеюсь, что смогу уделять каналу больше времени, чем в сложном 2020-м.

Если вы хотите поработать со мной в команде, пишите в личку @nick_volynkin хоть сейчас. Добавьте резюме и примеры работ, лучше на английском.

Привет! Меня зовут Николай Волынкин и я руковожу командой документации Tarantool.

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

Будет полезен опыт разработки, администрирования или работы в техподдержке. Здорово, если вы знакомы хотя бы с Git, командной строкой и языками разметки. Если не знакомы, мы вас научим за пару недель.

Про что мы пишем
— Tarantool («Тарáнтул») — база данных и сервер приложений, работающие в оперативной памяти, то есть очень быстро. В Tarantool можно писать логику обработки данных на языке Lua. Это тоже очень быстро работает и удобно в разработке*.
— Cartridge — конструктор для разработки и управления кластером баз данных.
— Tarantool Data Grid (далее TDG) — платформа для анализа данных, которой удобно пользоваться не-разработчикам.
— Модули Tarantool, коннекторы для разных языков программирования, инструменты для развертывания.

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

* Пишу упрощенно. Если вы видите тут кучу ошибок, то вы, наверное, разработчик. Для вас есть другая вакансия.

В чем ценность документации
Тарантул — внутренняя разработка компании Mail.Ru Group. Компания использует его во многих своих проектах (например, почта и облачный сервис МСS). Есть и внешние пользователи. Обычно это крупные банки и телекомы.

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

Кто нас читает
— Разработчики в команде Tarantool, в других подразделениях компании и во всём мире. Для них мы пишем про устройство базы данных, разработку приложений на Lua и другой хардкор.
— Разработчики, которые интегрируют Tarantool в другие системы. Для них мы описываем API коннекторов на C++, Python, PHP, Go и Java.
— Администраторы, которые занимаются развертыванием, мониторингом и поддержкой инсталляций Tarantool, Cartridge и TDG. У нас есть Ansible-роль для развертывания «на железо» и оператор для Kubernetes. Про всё это мы тоже пишем.
— Аналитики, которые используют в своей работе веб-интерфейс TDG. Им мы рассказываем про интерфейсы и сценарии в них.

Как мы работаем
Используем подход «документация как код». Пишем исходники документации на языке разметки, версионируем с помощью Git, все задачи и ревью (рецензирование) — на GitHub. Благодаря этому у нас всё публикуется за 10-15 минут, форматирование не ломается, тексты не теряются, картинки не пропадают. Про любую строку можем сказать, кто, когда и зачем её редактировал.

Ядро Tarantool — продукт с открытым исходным кодом. Большая часть исходников документации тоже открыта и лежит на GitHub. Командный стайлгайд ведём в общей документации.

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

Если интересны детали — мы используем Sphinx, reStructuredText, немного Markdown, локально собираем в Docker, используем GitLab CI и Travis, но переезжаем на GitHub Actions, в тесты добавим Vale.

Как откликнуться на вакансию
Пишите на n.volynkin@corp.mail.ru с пометкой [Вакансия] в заголовке. Прикрепите резюме в формате PDF или DOCX. Здорово, если добавите ссылки на примеры ваших текстов. С вопросами приходите в личку @nick_volynkin.

Лекция про документирование API в Confluence: https://youtu.be/yC89zNQSipE.
Рассказывает Олег Игонин, системный аналитик из Veeam Software.

Вводная от автора:

Хочу рассказать о том, как у меня сложилась работа с описанием API методов в Confluence для постановки задачи на их реализацию разработчикам (структура страниц в confluence, структура заголовков, некоторая автоматизация, описание интерфейса метода и работы логики под капотом).

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

В общем, возьму лампу, кота и буду рассказывать. xD

Есть такой подход к организации работы технической поддержки — KCS, knowledge-centered support, поддержка, основанная на знаниях. Строится на простых принципах:
1. Каждый запрос от клиента сначала ищем в базе знаний. Даже если решение вроде и так понятно.
2. Если находим статью с описанием решения — используем это решение. Дополняем статью, если есть чем.
3. Если не нашли — решение нужно выработать, применить и записать в базу знаний.
4. Публикуем все статьи, которые можем, чтобы клиенты могли сами найти и применить решение.
5. В базу знаний пишут все. Ведущие инженеры от новичков отличаются только тем, что решают и описывают самые сложные задачи.

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

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

А как у вас? Какие решения вы производите? Как сохраняете их, как делитесь с коллегами?

Принципы knowledge-centered support можно применить в ревью текстов или кода.

Вчера обещал рассказать, как применяю в работе принципы KCS. Так вот, я вдруг осознал, что уже два месяца использую похожие правила при ревью текстов и переводов:

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

Что из этого получается? За последние два месяца командные доки неплохо так приросли и уже экономят время на ревью и передачу знаний. И бóльшую часть текста написал не я.

Конечно, я делал так не всегда. Теперь буду делать осознанно и регулярно.

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

К этому посту у меня есть вопросы, но я забыл их задать. Исправляюсь.

Как у вас устроено ревью кода или текстов? Опираетесь на явные правила или только на личный опыт ревьюера? Как отличаете субъективные и объективные замечания?