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

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

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

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

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

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

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

Если что - предыдущее сообщение дополяется вот этой гуглодокой https://docs.google.com/document/d/1PEdUSz35jB1RU4mXjpsNh_ce7nNfvJLSB7ZtmsUHDrY/edit#heading=h.a0kv8gkktldn
Там можно оставлять комменты-предложения. Ну или можно обсудить его в чатике.

Если кому интересно, как решена вышеописанная проблема. До финала ещё не дошла, но я уверен, что путь выбран правильный.

1. Манифесты-фигесты пошли к чёрту. На словах не удалось договориться
2. Я завёл в gitlab-е шаблоны для всех issue (в конце сообщения будет пример) и потребовал, чтобы вся активность укладывалась в них. А то, что не укладыватся/идёт в обход я мониторю и разбираю индивидуально, по аналогии.
3. В гитлабе же завёл простейший воркфлоу: backlog, in analysis, task formed, doing, review, complete.
4. Переходы backlog -> in analysis -> task formed решаю я лично, с помощью тимлидов и 2..3 самых компетентных инженеров в компании
5. Связку task formed -> doing -> review делают техписы и инженеры. Ревью делаю я.
6. Список шаблонов для issue будет дополняться и они будут переписываться, инфа сотка. Кроме того, для сложных кейсов вроде "написать гайд из 5..7 документов" мне нужно будет первое время писать костяк на стадии in analysis, а постепенно сформируются шаблоны и для таких костяков.

Примеры шаблонов issue:

# Статья о решении проблемы

**На кого ориентирована статья**

- [ ] DevOps инженеры
- [ ] Ops инженеры
- [ ] Новички
- [ ] PM-ы инженерных команд
- [ ] Менеджмент компании

**Какую проблему решает эта статья**

@todo: описать

**Кто сказал, что проблема существует?**

- [ ] Личный опыт
- [ ] Тимлиды
- [ ] Менеджмент

**В какой момент эти люди сталкиваются с проблемой**

@todo: описать

## Как пользователи должны выходить на эту статью?

[ ] Через поиск

@todo: описать, по каким запросам доступна статья

[ ] Через закладки 

@todo: описать, как до людей будет донесено существование этой статьи

[ ] Через меню

@todo: описать, в каком разделе должна быть эта статья

## Внедрение

@todo: описать, как планируется внедрять эту статью и когда ожидаются первые merge request-ы от пользователей (дату)

Минутка юмора на канале

отказоустойчивость менеджеров

В то время как тимлиды находятся под пристальным вниманием (онижпродуктделают!), менеджерская братия зачастую предоставлена сама себе. Разберётесь ли вы в хитросплетениях договорённостей с Важными Людьми, если менеджер завтра траванётся и отлежится денёк-другой? Это будет мучительно. Я расскажу о рецепте, к которому пришёл.

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

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

На самом деле, если вы не хотите упороться по юридической стороны вопроса, а хотите всего лишь упростить смену ПМа, вам надо не так много:
- summary "кто этот человек, с которым договаривается ПМ, какие у него личные закидоны, какая атмосфера общения с ним"
- последние 5..10 событий, которые происходили. Под событиями мы имеем ввиду: афтермитинги, планы, обещания, статус-чеки. Причём самое интересное, что они могут быть оформлены в виде "ленты фейсбука", когда старые сообщения существуют, но вряд ли кто-то их когда-нибудь увидит.
- относительно регулярные "учения" по смене ПМа

Вооружившись этими утверждениями остаётся лишь сделать удобный инструмент, чтобы фиксировать договорённость быстро, в том канале, где вы общаетесь с клиентом. Чтобы не тратить время на поиски _той заветной гуглодоки где это надо дописать_ или где нужно почитать.

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

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

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

И очень хочется процитировать слова Линуса Торвальдса: talk is cheap, show me the code.
Смотрите в корень, господа и дамы. И очень учитесь отсекать, когда ваши слова и мысли основываются на *вашем* опыте, а когда - на чужих лейблах и предубеждениях.

Про слова
Talk is not so cheap, на самом деле.
Правильно сказанные слова и навешенные лейблы, в правильное время, нужным людям могут сотворить чудо.
Я говорю сейчас про сказку, связанную с вдохновлением людей, с объяснением им смысла того, что они делают и общей картинки. Очень часто в сильно иерархичных компаниях забывают об этом.
Инженерам, разработчикам, дизайнерам и прочим техписателям *нужна* общая картинка. Им *нужны* мечты о том, куда они могут вырасти и кем стать. И здорово, если кто-то умеет в них это вкладывать.
Можно заставить людей сделать корабль и получить корабль.
А можно вложить в людей мечту о море и получить флот.

Инструменты технического менеджера
Расскажу о своих ежедневных тулзах на состояние августа 2018.
- Slack - все коммуникации в команде идут через него. В качестве резерва - экстренный канал в Telegram, где есть почти вся компания.
- Google Meet - если разговор в слаке длится больше 5 минут и/или создаётся ощущение непонимания/конфликта - бегом говорить голосом. Google Meet очень стабилен, позволяет писать видео и нормально кроссплатформенный.
- Google Calendar - если он правильно настроен, то создавая мероприятие вы сразу можете позвать коллег (GCalendar делает автокомплит) и автоматом создать ссылку для встречи в Google Meet. Очень удобно!
- Google Docs - без комментариев :) Помните, что нельзя делать файл доступным "всему интернету", только - "всей компании".
- KeePass/KeePassX - у меня порядка 300..400 паролей, хранить их в голове и вспоминать, что ключевые нужно регулярно сменять - невозможно. Есть ещё интересное совместимое решение KeeWeb, но его пока не распробовал.
- Учёт задач. Рабочие - в нашем корпоративном сервисе (о котором как-нибудь отдельно), личные - в Trello. Я не заморачиваюсь с "датами окончания", а в трелло для личных дел у меня колонки "Идеи", "Сегодня", "В работе", "Сделано", "Заброшено".
- Учёт времени. Я вообще гик учёта своего времени, ибо убеждён, что это единственное, чем я по-настоящему владею. Рабочего - в корпоративном сервисе (вот он прямо офигенный, как-нибудь расскажу!), личное (когда я не с семьёй и не сплю) - в Toggl. Toggl, кстати, хорошо дружится с треллой.
- VSCode. Вообще я фанат решений Intellij, но последние полгода приходится работать не с каким-то одним языком, а со всеми сразу. Решение от Intellij на этот случай дороговато.
- скриншотлика. Сейчас использую встроенную в Ubuntu, если вдруг её будет не хватать - буду искать ту, которая позволит загружать файлы в корпоративное хранилище (ибо картинки на левом сервисе, вылезающие в выдаче гугла - это очень больно для NDA и безопасности, например). Кажется, monosnap так умеет.
- theoldreader - самая приятная RSS читалка

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

Две очень больных проблемы в коммуникациях инженерных команд
- потеря фокуса внимания - больная и регулярная проблема, как только вопрос выходит за рамки решения сугубо технической проблемы. Трёп ни о чём, разговоры о сторонних проблемах, тухляк и расслабон - все это свидетельства потери фокуса. Хорошо понимающие смысл встречи и свои цели от этой встречи люди так не делают.
- отсутствие подготовки ко встрече. Люди приходят на встречу с клиентом / на обсуждение зарплатных ожиданий / на командный митинг и не понимают чего они хотят от этой встречи. Типа, вот он я такой молодец, сейчас что-нибудь замутим. Фу такими быть!

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

А главное - не проводите встреч "для галочки"!

Всегда надо оставлять человеку возможность сохранить лицо в переговорах.
И всегда нужно предоставлять ему выбор. Даже если выбора на самом деле нет.

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

Если вы упираете на формулировки в Agile-манифесте и слова авторитетных людей - обратите внимание на Constraints (http://agilemodeling.com/artifacts/constraint.htm)

Разработчики не хотят писать документацию - они любят писать код. Они не умеют и не хотят осваивать русский язык, с его сложными оборотами и неоднозначными формулировками. Однако именно разработчики и инженеры являются носителями знания о продукте. Если на крупном проекте не будет хорошей внутренней документации, то вы обрекаете себя на более трудную отладку багов, на чудовищный bus factor и полную непрогнозируемость работ.

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

Я считаю, что решение ребуса существует.

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

Не обязательно документация - это выверенные тексты, но обязательно - это структурированная и, что гораздо более важно, обновляемая информация. Обновляемость документации - это ключевая метрика.

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

Есть решение.

Будильник.
Научите новичков ставить будильник на окончание очередного этапа решения задачи. Если не помогает - заведите будильник себе и бейте новичка по голове.

Будильник. Есть во всех компьютерах мира.

Про рефлексию и коммуникации

Управленческие фреймворки, пафосные фразочки из интернетика - это круто. Но, к сожалению, это так не работает.

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

Плохо:

Старший: Сходи, поговори с клиентом
через 2 дня
Старший: ну чё, поговорил? Чё он сказал? А ты чо? Ну тебе надо было сказать вот это и вот это.

Хорошо:

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

Профи отличается от новичка тем, что профи видит ключевые точки. У него глаза и уши настроены так, чтобы из общего потока информации выфильтровывать самое важное.
Вам нужно научить своего падавана смотреть на правильные вещи.

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

и многое другое. Закапывайтесь только в те темы, в которые надо будет конкретно с этим человеком.

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

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

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

Не нужно делать много, нужно делать то, что нужно делать. А так как последнего мы не знаем наверняка - надо пробовать.

Не ходи в историю с матрицами компетенций.
Не ходи в историю с матрицами компетенций.
Не ходи в историю с матрицами компетенций.

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

Матрица компетенций нужна крупной корпорации, чтобы на 1000+ сотрудников понять "а чо там вообще происходит". Пытаться сделать некий высер на 10..100 сотрудниках-айтишниках, в разрезе по технологиям/фреймворкам/уровням компетенций - обречённая история.

Хочешь опровергнуть? Стучись: @i_tsupko

Тут на тимлидконфе народ кипишует на тему перфоманс ревью и сбора фидбэка сотрудникам.
И есть у меня несколько пожеланий на сей счёт.

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

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

2. Цель руководителя (который обязан быть на перфоманс ревью!) - узнать у самого сотрудника, А ЕСТЬ ЛИ ПРОБЛЕМА?
Если у руководителя представленные факты вызывают боль - так и надо об этом сказать, но выводы о том, есть ли проблема или нет - должны родиться именно в процессе перфоманс ревью.
До момента этого совместного обсуждения проблемы нет. Поступившие вам факты могут быть ложными и картинка может быть не полной.
Если же факты серьёзные, а сотрудник уходит в тупую отказку - руководитель всегда может сказать я всё-таки считаю, что это проблема. Но если сотрудник с этим не согласится - грош цена вашему ревью, положительных изменений вы не добьётесь.

3. После того, как вы согласились о существовании проблемы вы вместе должны прийти к возможным путям решения. Причём сначала эти пути решения должен предложить сотрудник, а только потом, сугубо в сослагательном наклонении и с расшаркиваниями - руководитель. Не правильно: это решается вот так. Правильно: если позволишь, добавлю ещё свой взгляд. Я бы решал проблему вот так и так.
Конечно же, это должны быть максимально конкретные шаги.
Плохо: не ругайся на клиентов матом. Хорошо - прийти к причине, почему человек плохо себя контролирует/считает, что мат в переписке с клиентами это ок. Докопаться до психологических поведенческих паттернов. По необходимости - провести в ближайшие 2..3 недели серию обучалок. По необходимости - уделять внимание поведению сотрудника в ближайший месяц и хватать его за руку. По необходимости - просить сотрудника когда он чувствует, что что-то идёт не так приходить за помощью.

Это кажется трудоёмким, но это единственно честный способ действительно прийти к изменениям, а не уповать на удачу и "ненуачо, мы ж людей наняли за большие бабки, пусть работают, твари!".
Любите людей, пожалуйста.

Как аккуратно войти в матрицу компетенций: что писать в скиллы?

Ключевая фигня с матрицей компетенций - что писать в скиллы.
Первый подход к снаряду - а давайте напишем то, чему реально нужно научить новичков? Получаем монстра типа такого: http://reqcenter.pro/wp-content/uploads/2017/05/competency_model.jpg
Тыкаемся-тыкаемся, и всё время обнаруживаем, что оценка весьма поверхностная. Сотрудники - разные, они прошли разную историю проектов. А если это ещё и хардкорные инженеры, а вы только-только пробуете запустить оценку - словите кучу троллинга в свой адрес.

Окей, давайте обощим!
Получаем что-то типа https://www.intervolga.ru/upload/medialibrary/cfe/cfe1b345b0493bfe34d7080dc7f766cd.png
Конечно, пример утрирован, чаще всего приходят к чему-то вроде такого: https://docs.google.com/document/d/1FVvoSY35YD4BfAkv-XYGRITFbE17pA7A-R6S76UVsBQ/pub
но проблемы останутся:
- часть реально имеющихся навыков пролетят мимо вашей картинки
- что-то будет слишком общим для вашей реальности
- субъективность оценки для "общих" вещей будет зашкаливать

и, самое плохое: выводы из полученной таблицы будут типа ну, Вася, надо тебе подтянуть MySQL.
Что - mysql? Что подтянуть? Нахрена, если в реальной практике у инженера не будет таких задач? Знания, курсы и навыки, которые не востребованы будут забыты уже через две недели.

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

Интересный факт, следующий из предыдущего поста:
Если фактически ваши сотрудники не решают новых для них задач (тех, которые вы замечаете через трекеры) - значит и нечего ассесстить.

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

Про длинные согласования документов
Не знаю, как вас, а меня вымораживают долгие согласования документа с кучей народа. Но иногда это не обойти, не объехать.
И вот идёт третья неделя, энная итерация правок. Оставим за бортом повествования вопрос "как не сойти с ума" - гораздо важнее "как дотащить это быстрее до конца?". Люди, с которыми нужно согласовывать-то уже тоже устали, у них появились другие *очень важные дела*, скорость коммуникаций падает, собирать всех на встречи по N раз в неделю - больно и бессмысленно.

Есть хорошее заклинание, которое можно применять в этот момент: Привет. В документе важные правки в главах <перечисление>. Ты поучаствуешь?. Разберём его:
- да, занятым людям надо давать summary изменений. Кратко.
- Не правильно говорить ответь, не правильно рассуждать о сроках, если вовлечения нет. Не правильно ждать согласования от невовлечённых людей. Правильный вопрос - вопрос о вовлечении.