DocOps

2021-05-06 16:01:08 Поймал себя на интересной штуке.

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

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

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

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

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

2021-04-28 13:33:44 Friendly Asked Questions #2 — про документацию

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

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

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

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


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

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

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

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

2021-04-20 10:02:04 I'd like to review your readme.

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

https://liw.fi/readme-review/ Открыть/Комментировать

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

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

Пока писал пост, увидел ошибку. Пойду исправлять. Открыть/Комментировать

2021-04-08 14:20:25 Сергей Колганов пишет, что в резюме ищет ответы только на четыре вопроса про кандидата:

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

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

https://t.me/psilonsk/1132 Открыть/Комментировать

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

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

2021-03-19 15:27:49 Какой хороший наброс :) Открыть/Комментировать

2021-03-19 15:27:42 У меня горит, извините.

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

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

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

2021-03-19 13:41:48 Если что, этот вопрос не про технологии, он про управление процессом разработки документации и её перевода. Есть цель: хорошие доки на английском, проверенные на корректность и язык. Они полностью переведены на русский и перевод тоже проверен на корректность… Открыть/Комментировать

2021-03-17 11:22:38 У меня сейчас есть интересная дилемма по организации работы над переводом. Чтобы её объяснить, сначала расскажу про механику перевода. Перевод устроен так: исходный текст нарезается на единицы перевода (translation units, TU). Заголовки, абзацы, пункты списков… Открыть/Комментировать