С декабря прошлого года я руковожу командой технических писателей в 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. Запись тоже будет, но позже.

Рассказывает Олег Игонин, системный аналитик из Veeam Software.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ревью перевода помогает обнаружить недостатки оригинального текста.

Мы пишем документацию tarantool.io на английском, а потом переводим на русский. Раньше переводили сами, а теперь отдали эту работу внештатной переводчице Кате. В целом это прекрасно и мы очень довольны. Доки наконец-то переводятся, а техписатели освободились для основной работы (привет, теория ограничений).

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

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

Другой типичный случай — когда код не размечен как код. Вот мы пишем про integer. Это абстрактное «целое число» или «переменная типа integer»? Разница существенная, мы всё-таки пишем про СУБД. Если это тип данных, то мы должны выделить его моноширинным шрифтом. Например: the Lua integer type can hold integer values from _____ to _____.

Вывод такой: переводчики ошибаются там, где ошибутся и многие другие читатели. Поэтому мы (писатели) берём на себя ответственность за все систематические ошибки в переводе. Изучаем их, ищем причину, вырабатываем правило,  внедряем его. Конечно, исправляем ошибки в оригинальном тексте и помогаем переводчикам исправлять перевод.

А что значит «внедрить правило»? Задокументировать, применять в ревью новых текстов, исправлять в старых, добавить в автотесты.

У меня сейчас есть интересная дилемма по организации работы над переводом. Чтобы её объяснить, сначала расскажу про механику перевода.

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

Внутри системы переводы хранятся в структуре ключ-значение (ассоциативный массив, dictionary, map). Оригинальный текст — это ключ, а перевод — значение.

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

Как вы думаете, что происходит, когда перевод уже есть, но вдруг поменялся оригинальный текст? Мы ищем по новому ключу, значения там нет, перевод «слетает».

Представьте, что есть старый текст на английском. Его написали давно, но ещё не перевели. Его нужно когда-то перевести, и когда-то вычитать и поправить язык, стиль и оформление.

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

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

Кажется, что оба варианта плохи, но второй — хуже. А можно как-то иначе? Отдать пруфрид переводчику или другому внештатному сотруднику? Что бы вы сделали?

Если что, этот вопрос не про технологии, он про управление процессом разработки документации и её перевода.

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

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

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

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

Всё это мне пока что очень непонятно, но очень интересно. Давайте соберемся и обсудим? Например, в эту пятницу, 19 марта, 16:00 Мск. Ссылку на созвон кину в чат незадолго до встречи.

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

У меня горит, извините.

Несмотря на то что Mail.Ru спонсирует разработку Tarantool’а, весь процесс разработки, в т.ч. дальнейшие планы и база обнаруженных ошибок, является полностью открытым. В Tarantool включены патчи от большого числа сторонних разработчиков.
Усилиями сообщества разработчиков Tarantool’а были написаны (и далее поддерживаются) библиотеки для подключения модулей на внешних языках программирования.

Продукт делает русскоязычная команда, документацию тоже пишет она. Почему же документация на русском выглядит как перевод бизнес-литературы издательства "Манн, Иванов и Фербер"?

Стыд-то какой, когда на Тарантул документацию проще читать на английском.

Какой хороший наброс :)

Пока в чате @docsascode идёт жаркая дискуссия про термины, рунглиш и не-рунглиш, я написал основу для командного руководства по использованию терминов. Это руководство поможет нам осмысленно выбирать термины, консистентно использовать их и не тратить силы на холивары.

Приходите обсуждать в пулл-реквест :)
https://github.com/tarantool/doc/pull/1973/files

Сергей Колганов пишет, что в резюме ищет ответы только на четыре вопроса про кандидата:

1. Умеет ли он грамотно писать по-русски?
2. Может ли передать мысль без канцелярита?
3. Внимателен ли к деталям: много ли в тексте опечаток?
4. Понимает ли, что в резюме надо выглядеть адекватным, а не демонстрировать богатый внутренний мир?

Здорово, что для техписателя три из них — про хард-скиллы. А если «в резюме» заменить на «в тексте», то и четвертый пункт. Мой небольшой опыт это подтверждает: уже в резюме видно, как человек пишет.

https://t.me/psilonsk/1132

Тем временем, в нашей командной документации появился самый неформальный текст. Раньше мы такого себе не позволяли :)

https://www.tarantool.io/en/doc/latest/contributing/docs/markup/code/#defining-what-code-is

Пока писал пост, увидел ошибку. Пойду исправлять.

I'd like to review your readme.

Тут человек предлагает ревью readme для опенсорсных проектов. В очереди уже 125 штук, разбирает по несколько в день.

https://liw.fi/readme-review/

Friendly Asked Questions #2 — про документацию

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

Ответы дали авторы каналов Уютный Адочек, DocOps и The Know All
А мы ждём ваших вопросов в: https://forms.gle/sKyaEuqQMMyFJBxJ8

@the_know_all — Лана Новикова

Документация — один из способов организовать коммуникацию по какому-то каналу. Это решение, а давайте вернемся к проблеме. Зачем документация и какую вашу проблему и проблему бизнеса она решит?
Проблема — неосведомленность сотрудников о том, что делается в другом проекте. Эту проблему может решить не только документация, но и, например, периодические демо, сессии обмена знаниями, shadowing (когда периодически специалисты из одного проекта переключают контекст и работают в паре с коллегами из другого в формате «тени»). Техническому директору это надо «продавать» в его терминах: ускорение разработки, снижение эскалаций, снижение рисков инцидентов.
В тему организации обмена знаниями между отделами есть хороший доклад Марии Палагиной


@docops — Ник Волынкин

Давай тут разделим проблему на три части.
1. Команда не пишет. Стань первым, кто начнёт это делать. Когда будешь в чем-то разбираться — делай заметки. Так у команды будет хороший пример. Постарайся рассказывать команде о том почему и как это делаешь, и замечать, как твоя работа реально будет помогать коллегам.
2. Тимлид не поддерживает идею документирования. Вы, наверное, сейчас теряете время на погружение в задачу и на изобретение велосипедов, теряете мотивацию людей, плохо учитесь на ошибках (и будете их повторять). Всё это напрямую мешает работе тимлида и ставит его задницу под удар начальства. Не предлагай тимлиду писать доки — предлагай ему помощь в его работе.
3. Техдир идёт на конфликт. Лучше приходить к техдиру с тем, что уже работает хоть на небольшом масштабе. И ещё, техдиру нужен запрос, который можно решить только на его уровне. Плохо: "Сделай так чтобы мой тимлид заставил нас писать доки". Хорошо: "Мы начали писать анализ инцидентов, это помогает, давай это распространим на всю компанию".

@lovely_it_hell — Цупко Игорь

Можете ли вы писать документацию самостоятельно, подавая пример коллегам? Если в компании не выделяют время на изменения и инициативы — возможно пора поменять компанию.
Описанные реакции — странные. Троллинг и агрессия руководителя в ответ на инициативу подчинённого — звучит не здорово.
Если я правильно понимаю, вы хотите вдохновить коллег, побудить их к действиям. Попробуйте покидать им хороших примеров (возможно вы просто сейчас более "насмотрены" на хорошую доку, чем они), докладов, пописать короткие посты в чатики команды — но без нажима и требований. Вода камень точит и со временем какие-то идеи осядут в головах.

Поймал себя на интересной штуке.

Когда-то, только начиная работать в айтишечке, я относился к фичам продукта как к конфетам в мешке. Сыпьте разных и побольше!

Потом я поработал тестировщиком и выработал совершенно обратную реакцию. Фича — это ж надо разрабатывать, тестировать, документировать, поддерживать её потом. Выбирая делать эту фичу, мы выбираем не делать какую то другую. Новая фича? Падажжи, а может не надо? Если есть возможность не делать, давай не будем делать.

Ещё у меня раньше похожее отношение было к найму людей. Вот казалось бы, большая команда делает больше работы, а тимлиду почёт и слава, что справляется с такой толпой.

Теперь я совсем немного проработал тимлидом и уже ловлю себя на обратной реакции. Когда говорят о найме, я сразу начинаю думать, а можно ли без этого? Это ж надо искать, онбордить (адаптировать-обучать нового сотрудника), организовывать, развивать и менторить. Делая всё это я выбираю не делать что-то другое. Например, не помогать текущей команде делать больше меньшими усилиями.

Не поймите неправильно. Онбордить и развивать людей мне очень нравится. И фичи делать тоже нравится. Просто раньше я был жадный, а теперь какая-то осторожность появляется. Лучше меньше, да лучше.

Friendly Asked Questions #3 — про уровень зарплат

Почему мы платим разные зарплаты сотрудникам на удаленке? У них одинаковые должности и обязанности, но один находится дома в Москве, а другой дома в Саратове.

Ответы дали авторы каналов Уютный Адочек, DocOps, Человек и Машина, Евгений Потапов
А мы ждём ваших вопросов в: https://forms.gle/sKyaEuqQMMyFJBxJ8

Евгений Потапов (канал @eapotapov_channel)@eapotapov_channel)

Платить на удалёнке разные зарплаты для разных регионов выглядит странной затеей в 2021 году. Такой тренд был давно (и не только в РФ), когда можно было в регионах с более низкими зарплатами нанимать дешёвые кадры, но, имхо, сейчас ситуация уже сильно изменилась и рынок сформирован компаниями, которые платят универсальную зарплату без привязки к региону.

Карен Товмасян (канал @manandthemachine)@manandthemachine)

Очень хороший вопрос! Тема скользкая и несправедливая, но зарплата чаще всего строится не на базе выполняемой работы, но по средней зарплате по городу/региону.

Поэтому даже приехав из уездного города N, где зарплата была 30к, в Первопрестольную, то ценник сразу обретает нолик с конца, что работает и в обратную сторону. Не вы первый задаетесь этим вопросом, кстати. 😉

Ник Волынкин (канал @docops)@docops)

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

Цупко Игорь (канал @lovely_it_hell)@lovely_it_hell)

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

Очередной вопрос ^^^ от @lovely_it_hell — про деньги, а не про управление знаниями. Отетил, как смог. Чтобы ответ был полезнее, вопрос хочется переформулировать, чтобы он был не о всеобщей справедливости, а о зарплате конкретного человека. Вот так: «что мне сделать, чтобы получать больше?»

Получаются два основных ответа:
— Субъективно: поменять работу на компанию в Москве или за границей, научиться лучше договариваться о деньгах. В этом нет всеобщей справедливости, но это может сработать. Однако, ничего советовать тут я не могу, с этим помогают карьерные консультанты.
— Объективно: научиться приносить больше пользы, прокачать для этого хард- и софт-скиллы. Тут можно поговорить о том, какие конкретно навыки помогают писателю быть полезнее и зарабатывать больше.