Пока мы работаем над дневником разработчика fuel-плагина, появление которого вы большинством голосов (43 — за, 5 — против, 19 — воздержались) одобрили, мы предлагаем вам почитать рассказ нашего технического писателя Ирины Поволоцкой о прошедшей недавно конференции “Гипербатон”. Это — сборище техписов, на котором они творят свои тайные обряды (зачеркнуто) — делятся друг с другом опытом. Поскольку каждый контрибутор OpenStack должен уметь не только писать код, но и объяснять сообществу, почему этот код имеет право на существование, мы не могли обойти вниманием такое знаковое событие. И вообще — у нас давно не было обновлений. Вдруг вы соскучились?

18 апреля, в субботу, прошел третий “Гипербатон” — конференция, организованная “Яндексом” для технических писателей и всех вовлеченных в процесс создания документации.
“Гипербатон” проходил в офисе “Яндекса” в Москве. На входе в конференц-зал всех приветствовал игрушечный магистр Йода.



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

Почему это важно нам?

При работе в open source вообще умение описывать программерскую движуху дает серьезные преимущества. Например, одобрение от команды, отвечающей за интеграцию партнерских технологий (а также плюсы в карму и в оценку кода), получает тот, кто в состоянии внятно описать свои действия. Если же говорить конкретно про OpenStack, то участие в сообществе разработчиков требует не только умения писать код. Огромное влияние на успех той или иной инициативы оказывает способность логично и коротко описать то, что вы делаете, обосновать необходимость вашей работы.

Вернемся на Гипербатон

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

Сказать что хотел ты?

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

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

Дарья Еремина обратилась к теме погружения в Большой Проект, в котором, на первый взгляд, очень легко утонуть. Воистину, проблема, знакомая любому техническому писателю, активно вносящему вклад в OpenStack community — количество мессенджеров, баг-трекеров, бэклогов просто зашкаливает и за всем этим, безусловно, необходимо следить и выполнять свою непосредственную работу качественно: создавать понятную документацию без фактических ошибок. Дарья представила проблему как работу с различными потоками: поток людей, задач, информации, времени и, безусловно, внимательность. Дарья совершенно точно отметила, что наши задачи иногда похожи на monkey business, но именно внимательность к деталям делает документацию точной.

Максим Ильяхов из Дизайн-бюро Артёма Горбунова фактически провел мастер-класс, показав легким движением рук, как сделать текст легким, читабельным, понятным для пользователя. Что особенно приятно, он представил ресурс для проверки текста на наличие “словесного мусора” — ненужных слов и оборотов, которые можно легко выкинуть без потери смысла. Самые внимательные нашли в презентации ошибки и получили забавную наклейку с черепом и прекрасным редакторским лозунгом.

Узнать что хотел ты?

Техписатели задали очень много актуальных вопросов: как писать для специалистов, использовать ли профессиональный сленг; как мотивировать техписателей на наставничество и можно ли учить не только новичков, но и друг друга; может ли техписатель найти критичные баги и заслужить уважение разработчиков — вот лишь общие контуры дискуссии.
Все это достаточно знакомо всем, кто вносит посильный вклад в OpenStack комьюнити, или занимается решением частных проблем, как в нашем случае (Fuel и Mirantis OpenStack).

Как это работает в Mirantis

Технические писатели в нашей компании работают в режиме многозадачности, стараясь одним глазом поглядывать за апстримом, а другим — за локальными вопросами, будь то обновление документации к новому релизу или фикс багов.
Однако нельзя забывать об отличительной черте Mirantis — открытости наших гайдов для всех желающих: любой может внести изменение и попросить нас прокомментировать изложенное, предложить лучший вариант или формулировку. Так что вопросы наставничества имеют для нас большое значение.
Конференция позволила мне пересмотреть подходы к решению именно наших open source задач и задуматься о создании дополнительных инструментов (таких как руководство по стилю), улучшении уже существующих, а также, возможно, о более понятном и прозрачном процессе контрибуции в документацию.
Спасибо “Яндексу” за чудесную возможность посмотреть на эффективность своей работы со стороны. Да пребудет с нами всеми сила… слов!

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