​​— Почему пользователи StackOverflow начинают вопросы со слова Say? Например:

Say “How to get data array for a numpy array with python"

— А потому что в документации такой пример.

За ссылку спасибо @factorized.

​​Люблю опенсорс за дружелюбие и удобство.

Техписатели из Xsolla опубликовали третью часть эпоса про непрерывную локализацию.

https://habr.com/ru/post/452580/

Прямо сейчас идёт
Гипербатон от Яндекса.

В программе девять докладов про документацию и локализацию в IT.

Трансляция: https://events.yandex.ru/events/hyperbaton/25-may-2019/

Сегодня и завтра идёт фестиваль «Российские интернет-технологии», #RITfest2019.

Как обычно, я постараюсь законспектировать десяток интересных докладов. Всё выложу на гитхаб: https://github.com/docops-hq/conf.
Если вы тоже на конференции и что-то записываете — присылайте пуллреквесты.

Если вы не на конференции — посмотрите открытую трансляцию из главного зала. Там собраны одни из самых популярных и важных докладов.

​​Продвижение опенсорс-проектов

Андрей Ситник из Злых Марсиан рассказывает на #RITfest2019 о продвижении опенсорс-проектов. Рассказывает очень чётко и по делу, я как технический писатель со многим согласен. Особенно понравилась инструкция, как написать три первых абзаца README.

Вот конспект: https://github.com/docops-hq/conf/blob/master/frontendconf/19/promoting-opensource.md

Столкновение мнений в двух докладах на #RITfest2019.

Представьте, что есть некая IT-компания. Эта компания хочет нанимать новых людей и оставаться привлекательной для уже работающих. На этом факты кончаются и начинаются предположения.

Предположительно, для найма сотрудников полезна репутация компании. Её можно заработать, например, если писать что-то полезное в техноблоги, на Хабр, Реддит и куда угодно ещё. Чтобы писать интересно и не ерунду, писать должны сами разработчики. Внезапно, разработчики не любят писать, они любят кодить. А ещё у пиарщика есть KPI на статьи, но нет власти, чтобы поставить разработчику дедлайн.

Как сделать так, чтобы разработчики писали статьи в блог компании?

Мария Круглова из KODE предлагает редактору сделать за разработчика всё, что только можно. Сформулировать тему, сделать из черновика или доклада готовый текст и вручить его разработчику. Вот её собственное определение роли:

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

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

Конспекты:
— Профессия «Ghostwriter», или Учим программистов писать статьи, Мария Круглова, KODE.
— Пишем не только код, но и статьи: как помочь разработчику стать техноавтором, Антонина Татчук, Авито.

​​Blameless environment: никто не должен писать качественный код

Продолжаем #RITfest2019. Кто хоть раз работал на плохой работе? Там где код плохой, и процессы плохие, и клиенты плохие, и вообще всё плохо? Кто был виноват в том, что всё так плохо?

Никита Соболев из wemake.services считает, что никто не виноват, а искать виноватых вообще вредно. Гораздо лучше исправлять ошибки на системном уровне и развиваться. Конечно, об этом просто говорить и сложно сделать. Никита, по его словам, выстроил в своей компании систему, в которой никто не виноват. В докладе он последовательно рассказывает о принципах, на которых строится такая система.

Если вы ещё не слушали ни одного доклада Никиты и не знаете про внутреннюю кухню wemake.services, я особенно рекомендую вам прочитать конспект или послушать доклад. Либо вам это очень понравится, либо вы будете дико возмущены.

Конспект: https://github.com/docops-hq/conf/blob/master/qualityconf/19/blameless.md

Сегодня доклад ещё можно посмотреть в трансляции, но скоро ссылка перестанет работать: https://youtu.be/V95bBGB-89Y?t=8561

Фестиваль РИТ продолжается, есть открытая трансляция второго дня: https://www.youtube.com/watch?v=a5kq-Yk28po

Написал бы анонс, но меня опередили :)

Большой молодец @Nick_Volynkin сделал конспект доклада Flant о werf с РИТ++ https://github.com/docops-hq/conf/blob/master/devopsconf/19/werf.md #flant

​​werf — наш инструмент для CI/CD в Kubernetes

Всё-таки напишу про werf и доклад о нём. Хочу сказать кое-что очень важное.

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

Я вот только начал сталкиваться с этими проблемами в нашем тулчейне для документации, а ребята из Фланта уже пять лет их решают и неплохо продвинулись. Доклад Дмитрия Столярова на #RITfest2019 — о проблемах с Docker и k8s и о том, как эти проблемы решает werf, новый инструмент для CI/CD в k8s.

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

Давайте им поможем. Вот прямо сейчас зайдите и поставьте звёздочку: werf. И обязательно попробуйте werf в деле.

Конспект: https://github.com/docops-hq/conf/blob/master/devopsconf/19/werf.md.

На картинке ниже синим — что уже реализовано в werf, жёлтым — планируется к концу лета.

«Проклятие знания» в действии.
https://ru.wikipedia.org/wiki/%D0%9F%D1%80%D0%BE%D0%BA%D0%BB%D1%8F%D1%82%D0%B8%D0%B5_%D0%B7%D0%BD%D0%B0%D0%BD%D0%B8%D1%8F

​​В русской википедии утверждается, что «наглядная работа алгоритма показана на рисунке» и дальше вот этот рисунок. Диплом о высшем математическом образовании дает мне силы сказать: это картинка не наглядная, а не мы тупые.

Не корите себя, если очень стараетесь понять что-то в разработке и не получается. Скорее всего, часть ответственности на учителе. Если речь о вашем разработчике — просите объяснить яснее, вы имеете право понимать.

Документация ≠ текст.

Осенью 2015 года я работал тестировщиком в 2ГИС и только начинал разбираться с Ansible. Читал наши ansible-скрипты, но ничего не понимал. Читал документацию и туториалы на docs.ansible.com, и тоже ничего не понимал. Чувствовал себя нубом.

А потом я посмотрел видео, где Джефф Гирлинг показывает простые ad-hoc команды на стеке из шести «малинок» (Raspberry Pi). И после этого смог выполнить эти же команды на своем тестовом хосте. А потом и всё остальное понял, и с удовольствием драйвил тему Ansible в команде, пока не уволился.

К чему это я. Документация — это не только текст. Есть другие способы донести до читателя технические знания: видео, схемы, гифки, выступление на конференции, подкаст. Они могут работать гораздо лучше, чем текст.

Вот то самое видео: https://youtu.be/ZNB1at8mJWY

Highload++ Siberia.

Мы с коллегами по сообществу Write the Docs снова идём на конференцию Highload++ Siberia. Если вы там будете — заходите к нам на стенд поговорить про документацию и управление знаниями.

Организаторы конференции — ребята щедрые и гостеприимные. Они дарят скидку 50% на билет всем участникам, которые платят сами за себя по промокоду Personal{DocOps}.

Если вы студент или преподаватель, то для вас скидка целых 75%, промокод Academic{DocOps}.

Вот сообщение от самих организаторов.

HighLoad++ Siberia 2019 – Профессиональная конференция разработчиков высоконагруженных систем.

24 и 25 июня 2019г. в Экспоцентре, Новосибирск, пройдет конференция для разработчиков highload-систем, которая соберёт 600 участников из разных регионов России и мира. Мероприятие направлено на обмен знаниями о технологиях, позволяющих одновременно обслуживать многие тысячи и миллионы пользователей.

Мы решили расширить аудиторию конференции Highload++ Siberia и предлагаем две новые возможности для участия:

+ Если вы студент, аспирант или преподаватель ВУЗа, то вы можете воспользоваться скидкой в 75% от стоимости билета - используйте скидочный код Academic{DocOps} при заказе билетов на сайте конференции. Имейте в виду, что при регистрации мы попросим вас показать любой документ, удостоверяющий ваш статус."

+ Если вы частное лицо и нет компании, которая компенсировала бы вам билет, то вы можете воспользоваться скидкой в 50% - используйте скидочный код Personal{DocOps}.

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

У нас тут возник спор о профессиях и ролях. Одни не берут на себя лишних ролей и задач, потому что за них всё равно не доплачивают. Другие выходят за рамки профессии и роли, и договариваются о более высокой зарплате.

А у вас как?

Поводом к спору послужил наш с Семёном Факторовичем и Евгением Галактионовым квартирник на #CodeFestX. Мы там говорили о профессиях аналитика и технического писателя, ожиданиях, требованиях и зоне ответственности.

А ещё у меня там половину времени очень странное выражение лица. Так уж получилось :)

https://youtu.be/h48ycbRFDsU

Как сделать так, чтобы документация не болела?

Мы с Семёном @factorized провели сегодня митап про документацию на Highload++ Siberia. Поговорили о типичных проблемах разработки, которые можно решать с помощью документации. Конечно, всё законспектировали. Вот, держите: https://github.com/docops-hq/conf/blob/master/highload/19/siberia/docs.md

Если вы были на митапе или вам просто интересна эта тема — давайте общаться дальше, заходите в чат @docsascode.