Как заставить людей докать и использовать доку?

Только меняя процессы, чтобы через доку шли коммуникации. И нет, это не противоречит "эджайл манифесту" и прочим модным вещам.
Как изменить подход к коммуникациям, если у вас нет власти - я хз. Если вы знаете - пожалуйста, расскажите в @tinyest_devil_secretary_bot.
Добивайтесь власти, чоуж.

Обращу ваше внимание, что "докать коммуникации" - это не обязательно возня с вики/гитлабом. Сообщения в слаке тоже могут быть первым этапом.
Важно: жесткий формат (чек-лист) на имеющиеся типы запросов, и (!!!!) обновление старых записей. Дока не считается внедренной пока ее не начали обновлять - это золотое правило.

Есть у меня наброски на маркдаун ide, которая прям очень красиво помогает с
- работой с докой даже менеджерами (ибо визивиг)
- процессам согласования
- совместной работой над фичами
И имеет чудовищно удобную расширяемость по фичам и интешрируется в другие решения по docs as a code.

В этой иде будет удобно запускать процессы документирования в компании, независимо от того - эджайл вы или кровавый энтерпрайз.

Если этот пост наберет
20 лайков - выложу на гитхаб концепт с функциональными и прочими требованиями и набросками макетов
40 лайков - приложу архитектурное решение с обоснованием. Практически готовая задача для разработчиков
60 лайков - в конец офигею и...ну не знаю, может сяду писать бэкэнд для утилиты.

Софт скиллз: всегда идите туда, где страшно

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

Тем не менее, я убеждён, что смелость, полученная тогда (я же выжил! даже с собаками! ;) ) помогла мне решить некоторые карьерные вопросы и вести переговоры с очень страшными людьми.

Объёмы документации

Интересная тема для обсуждения - объёмы документации. Документацию вообще обычно пишут на "сложные продукты" и в "крупных проектах". Но, как ни странно, даже в крупных проектах отношение публичной документации к внутренней, для разработчиков, скорее 10 к 1.
На мой взгляд это отношение должно быть как минимум 1 к 1, а то и 1 к 10.

А давайте обсудим это в @TeamLeadTalks?

​​Документ готов, когда его начали дополнять

Продолжаю делиться идеями, добытыми на двух конференциях. Игорь Цупко, директор по R&D в компании Флант, так определяет definition of done для внутренней документации:

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

Если не дополняют — ищите причину:

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

— Люди не умеют/боятся пользоваться инструментами для дополнения документа. Да, так тоже бывает на ранних стадиях жизни. Каждого нужно провести за ручку или обеспечить механику, чтобы кто-то его проводил за ручку.

— Люди боятся вообще писать. Тогда нужно дать им в помощь писателя, чтобы тот оформлял их мысли.

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

— Документ никому не адресован. Для работы с этим аспектом есть отличный инструмент — граф коммуникаций. Это ещё одно сокровище, добытое на конференции и о нём тоже будет отдельный пост.

---

Игорь пишет заметки о руководстве командой и управлении знаниями в @lovely_it_hell.

Вот он что-то эмоционально рассказывает на митапе про управление знаниями в инженерных командах:

Про обучающие курсы: приёмы из тренинг-тусовки

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

Урок можно строить по простому и надёжному паттерну:

- делайте вводное объяснение, чему вы будете сейчас их учить. Установите временной регламент и фокус внимания на правильные вещи. Когда вы будете рассказывать о том, что предстоит - люди мысленно уже начнут выполнять ваше задание.
Вводное объяснение может быть: просто речью лектора, короткой демонстрацией вместе с кем-то (в режиме парного программирования), видео/презентацией на 2..3 минуты.

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

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

- встройте опыт в повседневную жизнь людей. Обсудите с ними, как они будут использовать полученные навыки, когда уйдут с урока. Что изменится, что они будут делать иначе, что попробуют прямо сразу?

Таким образом мы повторяем примерно один и тот же материал 4 раза в разных форматах.

Набросал коротко концепт.
https://github.com/may-cat/markdown_ide/
По всем вопросам - @i_tsupko.

Прошу вас дать чуток фидбэка по поводу markdown ide :)
public poll

не впечатлило – 6
👍👍👍👍👍👍👍 50%
@aladmit, @Andreichernov, @strukov, @Tash1ro, @SuckMyNuts, Кирилл

крутая тема, я бы покодил в команде – 3
👍👍👍👍 25%
@aa74ko, @koncevoisasha, @drforest

крутая тема, я бы поюзал – 2
👍👍 17%
@Nick_Volynkin, @Constantine_f

нафиг это всё, даёшь больше постов про айти адочек! – 1
👍 8%
@staticsealedabstract

👥 12 people voted so far.

Есть такая классная штука - называется "ситуативное лидерство".
Вы видели ситуации, когда на встрече все сидят в телефонах/ноутбуках и занимаются своими делами и Один Большой Дядя что-то вещает? Конечно видели.
Более интересный случай - это когда участники действительно вовлечены, их глаза широко раскрыты, они сидят вертикально или наклонившись вперёд, активно жестикулируют и зачастую перебивают друг друга, их голоса громкие и чёткие.
А что делает Большой Дядя, когда оказывается в такой ситуации?
Как ни странно, зачастую начинает бояться за своё лидерство, пытается подавить активно вовлечённых людей и устаканить свою доминантность.
В такой ситуации "большого дяди среди увлечённых людей" может оказаться любой начинающий тимлид. Старайтесь избегать этого и осознать
- то, что группа вовлечена - это _ХОРОШО_. Это значит группа "раскачалась" и обрела высокую динамику, она может выдать крутой результат (или не выдать)
- в хорошо "разогнанной", динамичной группе нет и не может быть явного лидерства. Всё лидерство - ситуативное, скипетр и корона ходят от одного человека к другому. И это тоже хорошо.
- если вы умный лидер - вам нужно аккуратно удерживать рамку и цель беседы, дабы разговор не ушёл в трёп о котиках и сиськах.
- если вы умный лидер - вы можете уступить место другому, когда это нужно, во имя целей группы.

Формулировка задач

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

Возьмём фразу система должна реализовать функциональность обратной связи. Когда вы её говорите - вы можете представить себе разных людей, которые как в фильме делают энное количество действий. Этакая нарезка из роликов.
Задача любой формулировки задач - описать эту нарезку роликов _максимально сенсорно_: картинками, звуками, движениями. И избегать: ощущений, обобщений, не-сенсорной информации ("дружба", "абстракция", "информация"). Нажми на красную кнопочку с надписью "отправить" - и увидишь синий попап с надписью "спасибо, ваше заявление принято".
Есть правда парадокс нашего любимого айти, что не-сенсорные термины ("модель") могут быть очень сенсорными (на примере той же "модели" - это прям очень конкретный кусок кода, который легко себе визуально представить).

И конечно, речь не про "идеальную формулировку", а про навык конкретизировать речь, с помощью задавания правильных вопросов.
Один из лучших сетов вопросов, которые я видел на этот счёт - это то, что в НЛП называют "метамодель языка".
Вот тут более-менее неплохая табличка на этот счёт: http://ways4you.ru/nlp-dlya-zhizni/metamodel-i-metamodel-ny-e-voprosy.html

Домашнее задание: взять какой-то маркетинговый буллшит текст, открыть список метамодельных вопросов и разметить текст этими вопросами.

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

Привет, канал. Мы с ребятами решились-таки поделать markdown ide, просто потому что можем :) Плюс надо чуток подготовиться к грядущим конференциям.
Недельку-полторы постов в канале не будет и потом я вернусь с новыми силами. В черновиках валяется много интересного, stay tuned.

В чатике @TeamLeadTalks прям очень хороших несколько тем и постов о том, как сподвигнуть людей на что-то, начиная с https://t.me/TeamLeadTalks/7877 (спасибо @Constantine_f за помощь с освоением передачи ссылок в Телеграме)

Я чуток залип в инженерные дела, и даже руки не поднимаются писать про технический менеджмент. Сорян.
Поделюсь пока одним вычислением, которое сделал намедни.

Моя паранойя периодически шепчет: "Заведи себе безопасный бэкап-сервер! Хватит бегать с жёсткими дисками! Только Raid-массив, только хардкор!"
Естественно, бэкап-сервер должен быть доступен для подключения только по VPN и закрыт от внешних воздействий. Естественно, он должен быть доступен с моих устройств, а в идеале - внутри VPN подключения должен быть доступ ко всем домашним инфраструктурам (чтобы можно было спокойно те же веб-камеры поставить) - впрочем, это уже следующий шаг.

Я полез смотреть - чего бы стоило сделать нормальный сервачок где-нибудь в Германии или Франции, с парой террабайт диска. И, с сожалением, пришёл к тому, что проще взять Raspberry Pi, подключить к ней два диска, сложить всё это в коробочку и поставить у надёжного человека дома.
Raspberry уже достал с полки, соображаю, как это лучше всё собрать в удобную коробку.

Возник вопрос - как делать "раскрытие" в sequence диаграме, генерируемой с помощью plantuml.
Условно говоря - рисуете вы описание работы системы трёх систем

Система1->Система2: хттп запрос
Система2->Система3: загрузка файла

Как сделать так, чтобы ту же Систему2 можно было укрупнить и увидеть, что происходит внутри неё?

Ответ найден - plantuml умеет выдавать свой результат не только в png, но и в svg. И тогда на помощь приходят ссылки http://plantuml.com/link
Сам ещё не пробовал, но выглядит вкусно, особенно если подобную конвертацию сможет органично сделать модуль plantuml для гитлаба. Надо будет попробовать, как руки дойдут.

У автора адовищного канала сегодня др.
Написать что-нибудь едкое, но по делу, можно тут: https://www.facebook.com/i.tsupko

Ещё одна минутка оффтопа.
Заменил стандартный роутер "от провайдера" на собственный (Mi Wifi), с функцией 5G. И понял, насколько отстал от жизни. Не мог себе представить, что по вайфаю можно выжать больше 5 мегабит, однако же.
Учитывая, что игрушка стоила не так много и решает кучу других проблем - считаю, что это хороший пример для подражания.

На примере знакомых компаний: шуточки про бегство.

Что бы вы, как тимлид/технический менеджер, делали, если бы в чате-флудилке разработчики регулярно шутили бы на тему "пора валить", "всё валится - время обновлять резюме", "сделал говна - пора увольняться"?
Давайте обсудим в @TeamLeadTalks.

"Чёто он мне не нравится"

Когда технический менеджер или тимлид говорит такую фразу про кого-то из своих инженеров (и не только про них, на самом деле), мол, наверное надо увольнять - это прям грустно.
Грусть увеличивается в разы, если это происходит в "супер-пупер эджайл организации".
90% проблем в людях (если мы говорим про адекватную выборку людей в IT) решается просто *ртом*. Не нравится что-то в поведении человека ("расслабился", "кажется не внимательный", "тупит") - дайте ему обратную связь. Сделайте это правильно, чтобы
а) понять, считает ли он это проблемой
б) донести до него, что вы реально считаете это проблемой
Конечно, для начала разговора вам нужно сформулировать - в чём конкретно проявляется _вот это вот, что не нравится_.
Если вы достигнете согласия в вышеописанном - уже можно обсуждать как эту проблему сотрудник будет решать. Сроки, промежуточные точки, какие конкретно шаги он начнёт делать прямо сейчас.

Адаптация новичков.

Кроме прочего управления знаниями, я сейчас выстраиваю процессы по адаптации новичков. Постарался максимум интересного в статью https://habr.com/company/flant/blog/419051/ о том, как я делаю это сейчас и какие векторы развития виднеются.

Как выстроить разработку внутренней документации

Игорь @i_tsupko спрашивает в чате @docsascode:

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

Как договориться? В программировании для этого есть фреймворки и паттерны. А с русским языком как быть? Он ж не компилируется и автотесты не напишешь.

Что важно в документации:

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

У вас тоже это болит? Знаете решение? Приходите в @docsascode, обсудим.