Как начать внедрять фиксацию знаний в компании.

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

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

Подробно всю эту тему освещал тут: https://www.youtube.com/watch?v=NGiN3df_YGc
В том числе в видео вы найдёте пример структуры доки и объяснение того, какую структуру доки нужно построить именно вам.

Тут поступило предложение сделать чатик для нашего канала. Мол, тимлидам и прочим сотрудникам ада надо обмениваться опытом. Если честно, я не фанат, но всё же.

Стоит ли делать чатег канала?
anonymous poll

Дааа! Больше чатов богу чатов! Тысячи их! – 21
👍👍👍👍👍👍👍 54%

Лучше запартнёриться с большим комьюнити и жить в интересном сообществе тимлидов – 10
👍👍👍 26%

Нет, нафиг, и так всё в чатах, задрало – 8
👍👍👍 21%

👥 39 people voted so far.

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

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

Если есть проблемы с использованием воли и с самодисциплиной - можно начать с выделение "самого главного дела на день". Добейтесь хотя бы того, чтобы закрыть его.
По мере того, как ваша жизнь перестроится (1..2 месяца, наверное) в связи с этим - можно начать выделять 2-3 самых главных дела и так далее.

Делюсь одной из лучших моделей, описывающих как начать писать статьи и художественные тексты.

Меня тут хорошо пропесочили за пдф-ку. Спасибо, @factorized (он, кстати, делает проект http://documentat.io).
Вот его подборка:
- если речь о публицистике, то есть неплохая «Автор, ножницы, бумага» Кононова, https://www.mann-ivanov-ferber.ru/books/avtor-nozhniczyi-bumaga-kak-byistro-pisat-vpechatlyayushhie-tekstyi/, но она не про технические тексты
- ближе к техписателям/копирайтерам лежит Ильяхов, https://book.glvrd.ru/ и его набор советов, https://soviet.glvrd.ru/

Всем привет! Мы теперь дружим с @TeamLeadTalks - и предлагается обсуждение постов вести там :) Всё официально и без консервантов.
Да здравствует единство технических менеджеров и обмен знаниями!

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

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

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

Технический менеджер: Мы будем переезжать на другой сервер на следующей неделе
Другая команда: Но у нас релиз в среду!
Технический менеджер: В среду убедимся, чтобы всё работало. Сообщишь за 2 часа до момента Х, что скоро покатите? Сколько вам времени на релиз нужно?
Другая команда: Ок. В идеале 2 часа, но скорее всего как обычно затянем на 5.
Технический менеджер: Договорились.

Управление знаниями: диагностика багов

Есть методология диагностики багов, которая повышает интеллектуальный уровень разработчиков, помогает со "сложными" багами и делает ваши волосы мягкими и шелковистыми.
Очень здорово, если ваши ключевые алгоритмы (они же - ключевые действия пользователей) будут описаны в виде sequence диаграм (https://cdn-images-1.medium.com/max/1820/1*vnSPuXKP9w7He0CBkLtaKA.png например). Колонки - это компоненты проекта. В парадигме микросервисной архитектуры это могут быть микросервисы, в парадигме монолита - например, модули.
Смысл заключается в том, чтобы научить инженеров представлять себе картинку процесса целиком и уметь его держать в голове. Потому что смысл любой диагностики сводится к половинному поиску по этой схеме: берём наиболее интересную точку, проверяем в ней состояние и делаем выводы, где проблема - выше или ниже.

Управление знаниями: диагностика багов, часть 2

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

Тикет: не загружаются файлы
Зашёл в Sentry - вижу ошибку, что кончилось место
Зашёл на srv1
Набрал команду df, места на /dev/sda1 1 мегабайт

Формат логгирования может быть произвольным (оптимизируйте так, чтобы это было комфортно), но суть в том, чтобы
- видеть, какие контрольные точки смотрит инженер
- какие выводы он делает из того, что видит
- сделать диагностику отчуждаемой (отладку сложного бага по этой методике можно перекинуть на другого человека без лишнего геморроя!)
- убедиться, видят ли инженеры "всю картину" ключевого алгоритма, не занимаются ли они тыканием "там, где светло", а не там, где искать нужно.

В любом случае, это хороший способ обучать людей.

Разбавлю серьёзные посты :) Приснился мне тут сон к стиле кибер-панк.

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

Обсуждаем документацию с @docops на хайлоад сибирь.
Основная боль пришедших - в мотивации людей. Как будто все хотят, но не могут.

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

Прямо сейчас обсуждаем документацию на Highload Siberia. Вот непрерывно обновляемый конспект: https://github.com/NickVolynkin/highload-siberia-2018/blob/master/docs-meetup.md

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

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