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

Меня тут хорошо пропесочили за пдф-ку. Спасибо, @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 раза в разных форматах.

Набросал коротко концепт.
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

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