Всем привет! Меня зовут Петров Сергей и я технический писатель-аналитик в Контуре.
В Контуре я не привязан к какой-то конкретной команде, я — член Бюро разработки. Мы приходим на короткие фиксированные контракты в подкоманды Контура, которым не хватает какой-то конкретной роли, закрываем потребность команды и выходим обратно.
Недавно я закончил очередной контракт и он показался мне очень показательным. Я приходил в команду, которая раньше жила без технического писателя. Вообще. Команда только-только переходила со стадии стартапа на стадию устойчивого развития и многие процессы в ней либо переходили на более устойчивую стадию, либо же, как документирование, появлялись впервые.
Это отличный повод рассказать, а что тех.писатель делает в команде, которая раньше работала без него, и зачем он этой команде вообще.
Что встречает писателя на входе?
Для всех команд, которые раньше жили без тех.писателя, картина, как правило, примерно одинаковая:
информация хранится в головах разработчиков, и некоторые разработчики не имеют представления о том, как работает соседний модуль;
база знаний отсутствует или в таком состоянии, что найти информацию в ней может только тот, кто уже знает, где она;
команда не знает как работать с тех.писателем, процессы документирования в команде либо отсутствуют, либо существуют в зачаточном состоянии.
Как с этим работает тех.писатель? Последовательно решает каждый вопрос, переходя от самых критичных к менее чувствительным:
исследует продукт и командные процессы;
повышает bus-factor;
возвращается к исследованиям;
пишет документацию на каждом из этих этапов.
Расскажу о каждом этапе подробнее.
Четыре стадии принятия
Исследования
Это первый этап через который проходит тех.писатель в новом продукте. Знакомимся с продуктом со всех сторон — от пользовательского функционала до взгляда на продукт с точки зрения разработчика. Смотрим, читаем, изучаем всё, что есть.
А ещё назначаем интервью-знакомства тимлиду разработчиков и, желательно, самим разработчикам, чтобы собрать с них информацию, что они знают в проекте, за что отвечают, о чём имеют представление, а что для них «Это Миша писал, спроси у него, я не шарю».
Самым важным артефактом по итогам этого этапа становится Карта Компетенций — таблица или майндмап, на которых представлены карта продукта и глубина погружения в контекст каждого из разработчиков.
Карта Компетенций помогает тех.писателю расставить приоритеты в работе, понять, какие точки в продукте наиболее критичны и что нужно документировать в первую очередь, чтобы повысить bus-factor в команде.
Один из вариантов, как может выглядеть Карта Компетенций:
По цветам: зелёный — знает о модуле всё; жёлтый — слышал о нём и даже видел, как он работает; красный — знает, кто написал этот модуль и на кого перенаправлять задачу в случае чего.
На этой карте компетенций пять модулей, о которых что-то знает только один из разработчиков. Это классический пример bus-factor’а. Об этом ниже.
Bus-factor
Bus factor — количество участников проекта, которое должно выбыть, чтобы проект остановился.
Если для того, чтобы ваш проект остановился нужно, чтобы из него выбыл всего один человек, то ваш bus factor = 1. Соответственно, чем bus factor выше, тем лучше.
Повышение bus-factor’а — приоритетная задача тех.писателя при входе в новую команду.
Что мы делаем:
Определяемся с целевой аудиторией статьи. Это поможет найти правильную глубину технической проработки статьи — пишем мы с точностью до строк кода и имён переменных или ограничиваемся верхнеуровневым описанием логики работы модуля.
Назначаем интервью разработчикам и просим их рассказать про модуль, в котором они шарят.
Пишем статью по итогу интервью.
Возвращаем статью на ревью разработчику.
Исправляем замечания и, в идеале, ещё раз отдаём статью на ревью.
Проводим кросс-ревью: отдаём статью с описанием модуля разработчику, который не знает о модуле ничего.
На кросс-ревью можно отдавать статью тестировщику или аналитику — любому представителю нашей целевой аудитории.Дополняем статью информацией, которая понадобилась второму разработчику.
На выходе получаем статью, описывающую одну из частей проекта настолько, что ничего не знающий о модуле разработчик сможет начать работу с этим модулем. Конечно, эта статья не сделает этого разработчика экспертом в работе незнакомого модуля, но она сильно снизит порог его вхождения.
Первый шаг к повышению bus-factor сделан. Теперь дело за МРом или тимлидом — они ставят разработчику задачу на работу с этим модулем и он с помощью нашей статьи пытается её решить.
PROFIT! Красная плашечка на карте компетенций становится жёлтой. Bus-factor растёт.
И снова исследования
Помимо больших и глобальных вопросов, в результате исследований тех.писатель обнаруживает много всего интересного, о чём разработчики не упоминали, потому что для них это очевидно или они просто забыли, что в продукте есть такая особенность. И это ок, потому что продукты бывают очень большими и сложными.
Здесь модуль отправляет запрос по неофициальному API, и мы получаем итоговое значение, которое выставляет сама площадка. Дальше мы проверяем…
Подожди-подожди. По неофициальному API?
Ну да, официальное API не возвращает итоговое значение, поэтому мы используем неофициальное.
А можешь подробнее рассказать?
И следующие полчаса слушаешь лекцию о методах прикладного реверс-инжиниринга API онлайн-сервисов.
В результате таких вот диалогов с разработчиками рождаются новые статьи, которые пишет тех.писатель. «Как устроен фронтенд», «Модуль работы прокси-серверов», «Неофициальные API онлайн-сервисов»…
Процесс документирования
А ещё тех.писатель организует здоровый процесс документирования внутри команды:
выбирает инструменты для ведения единой базы знаний;
непосредственно создаёт единую базу знаний в одном общедоступном месте;
организует понятную структуру базы знаний — это поможет сориентироваться новичкам или разработчикам, впервые попавшим в базу;
интегрирует процесс документирования в общекомандные процессы — от своих задач на доске разработки до внедрения обязательного этапа «Документирование» для новых фич в проекте;
постепенно прививает культуру документирования команде — в данном случае писатель выступает драйвером команды, который своим примером показывает, как именно должна вестись документация, где её писать и т.д. Иногда ведь разработчику для того, чтобы начать писать документацию, нужно просто преодолеть страх пустого листа и приходить писать в уже наполненное пространство.
Что в итоге?
В моём случае я был в команде на временном контракте, поэтому имел возможность сравнить состояние документирования в команде До моего прихода и После.
Что тех.писатель оставляет после себя:
высокий bus-factor;
обмен контекстом между разработчиками внутри команды;
база знаний с подготовленной структурой и первым пулом статей;
командный опыт взаимодействия с тех.писателем — наглядное представление о процессах и пользе нахождения тех.писателя в команде;
road map для команды, как жить без тех.писателя.