Привет, Хабр! Я Катя из команды техписателей в Ozon. Мы продолжаем расти и развиваться, поэтому вслед за статьёй о видах документации хочу разобрать, какие проблемы внутри команды можно документацией решить.
Если вы из команды, у которой нет ни документации, ни технического писателя, но паучье чутьё подсказывает, что беда близко и предотвратить её можно именно качественной докой, — в этой статье будем разбирать, в каких случаях документация может помочь.
В самом начале вам надо подумать, где могут быть проблемы, и обратить особое внимание на эти места. Понаблюдайте за командой, поспрашивайте, какие боли есть у соседних команд. Запустите человека из другой команды в свой проект и посмотрите, с какими вопросами он к вам придёт.
Дальше моя личная подборка частых болей, напишите в комментарии своих фаворитов ????
У меня не запускается ????
Ситуация: у Васи сегодня первый день в компании. Ему дали ссылку на репозиторий и огрызочную документацию, чтоб он тихонько сам разобрался, а завтра уже получил свою первую таску. Пока Вася разбирался с проектом, оказалось, что надо поставить кучу пакетов и зависимостей. Вроде всё поставил, консоль перестала ругаться, а всё равно не работает как надо. И теперь Вася сидит и переживает, что же о нём подумают коллеги, если он даже проект запустить не смог. Поэтому и вопросы не задаёт, а продолжает грызть кактус.
Тяжесть проблемы: есть проблема в неочевидных настройках и дырявых инструкциях. Но большинству коллег с ней живётся спокойно, поэтому страдать будет только Вася.
Решение: берём человека из другой команды и просим сделать какую-то мелочь в проекте. Если человек сломается или потратит в разы больше времени, чем ожидалось, то попросите его же записать, с какими проблемами он столкнулся. Положите эти проблемы в основу будущей инструкции. Если человек сам спокойно разобрался — тут нет проблемы. Можете повторить эксперимент на новичках и их же попросить написать или дописать документацию: они и в проекте разберутся, и проблемные места подсветят, и с командой познакомятся.
Не понимаю, как оно работает ????
Ситуация: Вася чуть освоился, запустил локально проект, даже внёс какие-то правки, но всё по максимально конкретным задачам от своего лида. Но вот лид в отпуске или на обеде, приходит менеджер и просит Васю перекрасить все кнопки в зелёный. Вася в панике, потому что так и не разобрался, где же функция перекраски кнопок. Пилит свою, новую и костыльную, ломает прод, откатывается, ломает тесты. Боль, паника, злые пользователи и руководство.
Тяжесть проблемы: работать можно, но сроки разработки сдвинутся.
Решение: просим лидов нарисовать UML для их зон ответственности, соединяем всё стрелочками и встраиваем в релизный процесс документацию. Без описания изменений где-то во внутренней Вики или на GitPages не выкатываем вообще ничего.
Подробнее про UML в продуктовой документации
Теперь Вася посмотрит на схему, увидит, где живёт UI-kit, и заменит одну константу, а не будет парсить код на наличие кнопок и перетирать им свойство цвета. Да и вообще обнаружит, что в зелёный кнопки уже перекрашивали три релиза назад.
Я ничего не трогал, оно само ????
Ситуация: кнопки перекрашены, заказчики удовлетворены, но тестировщики замечают, что после Васиных правок проект невозможно собрать локально. Вася свою вину отрицает. Лид вернулся с обеда, почесал макушку и вспомнил, что что-то подобное случалось. Вот только что именно и как лечили — никто не помнит.
Тяжесть проблемы: полная блокировка работы команды.
Решение: вести страницу ошибок. То, что вы сломали однажды, кто-то обязательно сломает ещё раз. Поэтому все неочевидные штуки, когда вы вроде бы ничего не трогали, а оно сломалось, нужно описать и сохранить. Ну и UML из пункта выше тут тоже помогли бы.
Частые вопросы и возражения
Можно вообще без документации?
Можно. Например, если в команде мало людей и они редко меняются, действительно бывает проще донести полезное знание голосом, чем поддерживать актуальность статей. Но убедитесь, что документация правда дороже других способов обмена информацией.
Иногда ещё помогает записать видео минут на 15, где разработчик объясняет, что он там такого сложного наделал, как это проверять и раскатывать дальше.
Документацию пишем, кучу времени тратим, а она не помогает — как так?
Значит, не то пишете. Или не в том виде. Остановитесь и подумайте ещё раз, какие проблемы у вас есть и какие из них достойны поиска решения.
Лид сказал делать документацию. А кодить теперь когда?
Документация не должна становиться обузой и наказанием. Обсудите всей командой, как встроить её в процесс так, чтобы никто не страдал. Оставьте только те документы, которые правда упрощают жизнь команды. Лайфхак: допишите в начале каждой статьи для кого она и о чём.
И наймите себе техписа.
Основная мысль: не ищите волшебную таблетку
Есть ненулевая вероятность, что и без документации у вас всё хорошо, а попытки заиметь доку будут сродни выстрелу в ногу. Первый шаг к счастливой команде всегда в процессах.
Посмотрите внимательно на происходящее в команде, предложите варианты решения насущных проблем. Предложите для начала просто попробовать новые процессы и ритуалы. Не навязывайте сразу — договоритесь на тестовый период и подумайте, что может быть маркером успеха.
Выпишите по пунктам свои боли за последний период, например:
Вася опять сломал прод, 100 раз уже говорили, что нельзя в конфиги лезть, а он снова туда коммитил.
Завтра новенький выходит, снова неделю лид будет только им заниматься, да ещё и нас отвлекать.
«Проще самому сделать, чем вам это объяснять» (с) лид.
А теперь на каждый пункт соберите необходимую информацию: Васе — страницу с правилами коммитов и со списком ошибок. Новенькому — страницу с пошаговой инструкцией по настройке окружения. А с лида попросите схему взаимодействия сервисов и поясняющую статью. А ещё список полезных книг и ресурсов.
Помните, что документация — не волшебная таблетка. Она, конечно, решает множество проблем, но разберитесь сначала в процессах. Если проблемы из-за дыр во взаимодействии всех и вся, то ни одна документация вас спасти не сможет.
Бонус! Как убедить лида, что вам пора брать техписа
Итак, ситуация: приходит разработчик к лиду и убеждает в необходимости найма технического писателя.
— Я тут подумал, у нас с документацией проблемы, давай, может, посмотрим технических писателей в команду? — робко спросит разработчик.
— Какие проблемы? — может ответить лид, искренне не понимая необходимость.
— Ну вот у нас Вася на прошлой неделе выходил, помнишь? — продолжает разработчик. — Прод в первый же день сломал. А всё потому, что у нас инструкция старая. На ней каждый новичок ломается. И вон девопсы пытались нам модули обновить месяц назад — тоже всё уронили. Был бы техписатель, посмотрел бы свежим взглядом на инструкцию и дописал все нюансы. Я бы и сам мог, наверное, но тогда в ближайшие спринты не уложусь. Да и перепишу я один раз, а остальные статьи? Ещё и поддерживать их надо. Не, я прикинул, тут работы на месяц.
— Вот именно, на месяц. А потом что?
— Так на месяц только актуализация уже написанных вещей. А остальные проблемы найти? А решить их? Техписатель потом в соседние команды пойдёт, им так же сделает. А там и наши доки обновлять пора будет. Ты вот на прошлой неделе спрашивал у тестировщиков, как у них система настроена — сколько в итоге встреч было? А так бы им грамотную доку техписатель сделал — они тебе б одну ссылку дали, ты по ней поискал и уже конкретные вопросы задал.
— Ок, я начал сомневаться, — отвечает тимлид, и разработчик уже грезит светлым документированным будущим. — Ну хорошо, чем занять найдём. А где мы человека возьмём, которому объяснять всё не надо будет, как в школе?
— Я на Хабре статью видел, там довольно подробно расписали, где искать специалиста. Действительно же много ребят на стыке гуманитарщины с техниной — у нас вон стажёр летом с филфака был, а какой бэк запилил, до сих пор хвастаемся!
— Ладно, давай посмотрим. Возьмём на испытательный срок, а там посмотрим. Не оставим, так хоть обновим существующую доку.
Пишите, о чём ещё стоит подробнее рассказать — моё техписательское сознание давно искажено и мне сложно понять без вашей подсказки, что же нужно миру на его пути к идеальной документации :)