Всем привет! Меня зовут Петров Сергей и я технический писатель-аналитик в Контуре.

В Контуре я не привязан к какой-то конкретной команде, я — член Бюро разработки. Мы приходим на короткие фиксированные контракты в подкоманды Контура, которым не хватает какой-то конкретной роли, закрываем потребность команды и выходим обратно.

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

Это отличный повод рассказать, а что тех.писатель делает в команде, которая раньше работала без него, и зачем он этой команде вообще.

Что встречает писателя на входе?

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

• информация хранится в головах разработчиков, и некоторые разработчики не имеют представления о том, как работает соседний модуль;

• база знаний отсутствует или в таком состоянии, что найти информацию в ней может только тот, кто уже знает, где она;

• команда не знает как работать с тех.писателем, процессы документирования в команде либо отсутствуют, либо существуют в зачаточном состоянии.

Как с этим работает тех.писатель? Последовательно решает каждый вопрос, переходя от самых критичных к менее чувствительным:

• исследует продукт и командные процессы;

• повышает bus-factor;

• возвращается к исследованиям;

• пишет документацию на каждом из этих этапов.

Расскажу о каждом этапе подробнее.

Четыре стадии принятия

Исследования

Это первый этап через который проходит тех.писатель в новом продукте. Знакомимся с продуктом со всех сторон — от пользовательского функционала до взгляда на продукт с точки зрения разработчика. Смотрим, читаем, изучаем всё, что есть.

А ещё назначаем интервью-знакомства тимлиду разработчиков и, желательно, самим разработчикам, чтобы собрать с них информацию, что они знают в проекте, за что отвечают, о чём имеют представление, а что для них «Это Миша писал, спроси у него, я не шарю».

Самым важным артефактом по итогам этого этапа становится Карта Компетенций —   таблица или майндмап, на которых представлены карта продукта и глубина погружения в контекст каждого из разработчиков. 

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

Один из вариантов, как может выглядеть Карта Компетенций:

На этой карте компетенций пять модулей, о которых что-то знает только один из разработчиков. Это классический пример bus-factor’а. Об этом ниже.

Bus-factor

Bus factor — количество участников проекта, которое должно выбыть, чтобы проект остановился. 

Если для того, чтобы ваш проект остановился нужно, чтобы из него выбыл всего один человек, то ваш bus factor = 1. Соответственно, чем bus factor выше, тем лучше.

Повышение bus-factor’а — приоритетная задача тех.писателя при входе в новую команду. 

Что мы делаем:

1. Определяемся с целевой аудиторией статьи. Это поможет найти правильную глубину технической проработки статьи — пишем мы с точностью до строк кода и имён переменных или ограничиваемся верхнеуровневым описанием логики работы модуля.

2. Назначаем интервью разработчикам и просим их рассказать про модуль, в котором они шарят.

3. Пишем статью по итогу интервью.

4. Возвращаем статью на ревью разработчику. 

5. Исправляем замечания и, в идеале, ещё раз отдаём статью на ревью.

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

7. Дополняем статью информацией, которая понадобилась второму разработчику.

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

Первый шаг к повышению bus-factor сделан. Теперь дело за МРом или тимлидом — они ставят разработчику задачу на работу с этим модулем и он с помощью нашей статьи пытается её решить.

PROFIT! Красная плашечка на карте компетенций становится жёлтой. Bus-factor растёт.

И снова исследования

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

• Здесь модуль отправляет запрос по неофициальному API, и мы получаем итоговое значение, которое выставляет сама площадка. Дальше мы проверяем…

• Подожди-подожди. По неофициальному API?

• Ну да, официальное API не возвращает итоговое значение, поэтому мы используем неофициальное.

• А можешь подробнее рассказать?

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

В результате таких вот диалогов с разработчиками рождаются новые статьи, которые пишет тех.писатель. «Как устроен фронтенд», «Модуль работы прокси-серверов», «Неофициальные API онлайн-сервисов»…

Процесс документирования

А ещё тех.писатель организует здоровый процесс документирования внутри команды:

• выбирает инструменты для ведения единой базы знаний;

• непосредственно создаёт единую базу знаний в одном общедоступном месте;

• организует понятную структуру базы знаний — это поможет сориентироваться новичкам или разработчикам, впервые попавшим в базу;

• интегрирует процесс документирования в общекомандные процессы — от своих задач на доске разработки до внедрения обязательного этапа «Документирование» для новых фич в проекте;

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

Что в итоге?

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

Что тех.писатель оставляет после себя:

• высокий bus-factor;

• обмен контекстом между разработчиками внутри команды;

• база знаний с подготовленной структурой и первым пулом статей;

• командный опыт взаимодействия с тех.писателем — наглядное представление о процессах и пользе нахождения тех.писателя в команде;

• road map для команды, как жить без тех.писателя.