В первой части ^[1] доклада мы в общих чертах рассказали, как измеряем качество документации и эффективность ее разработки. Теперь погрузимся в детали подсчета метрик.

Рассказывает Юрий Никулин, руководитель службы разработки технической документации.

Для начала давайте определим, что такое производительность. В классическом понимании, это время на производство единицы продукции или количество продукции, произведенное в единицу времени.

Например, это количество произведенных телефонов за месяц или количество времени на производство тысячи телефонов. Возникает вопрос, как измерять интеллектуальный труд, которым занимается наш отдел.

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

Мы выделили несколько критериев для отбора метрик:

1. Прозрачность. Подход к расчету метрик и трактовка результатов должны быть понятны не только нам, но и заказчикам.
2. Доступность данных. В том числе данных за какой-нибудь прошлый период, чтобы выдвигать гипотезы и пробовать подтвердить их историческими данными.
3. Возможность автоматизировать подсчет. Мы точно не хотим считать метрики руками.

В итоге мы поняли, что идеальный объект для подсчета метрик производительности — это задача в Трекере. Она отвечает всем требованиям, которые мы предъявляли к метрикам.

Источником данных для нас стал Яндекс.Трекер. Он достаточно гибкий и легко настраивается под наши задачи. Там уже есть все необходимые данные, потому что мы ежедневно пользуемся этим инструментом. А еще у Трекера есть API, значит, можно использовать эту информацию и автоматизировать процессы.

Так у нас появился план, как действовать дальше.

Настраиваем очереди и задачи

Начать нужно с выбора очередей, иерархии задач, их типов и статусов.

Об этом подробно рассказывала Катя Куненко в докладе «Инструменты для подготовки пользовательской документации ^[2]». Мы же коротко расскажем об организации очередей и задач, которую используем сами.

Очереди

У нас есть три очереди, которые по сути отражают нашу целевую аудиторию.

Иерархия задач

У наших задач двухуровневая структура:

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

Типы и статусы задач

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

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

Расскажем на примере графика. Например, баг исправляют в течение 1−5 дней, а на написание нового документа уходит 30−40. При этом новые документы мы пишем реже, чем дополняем старые или исправляем ошибки. Поэтому среднее время выполнения задачи любого типа (зеленая линия) слишком большое для багов и слишком маленькое для новых документов. С его помощью мы получаем только усредненное представление о скорости решения задач.

Поскольку мы считаем метрики, чтобы оптимизировать процессы, нам нужно смотреть на более точечные срезы: например, как долго мы решаем задачу «баг» или «новый документ». А среднее по всем типам можно смотреть для отслеживания общего тренда.

Мы используем такой набор типов задач.

Статусов больше, чем типов, потому что этого требует workflow.

Работать с типами и статусами проще, если они однозначные и их не слишком много. Иначе исполнители могут запутаться.

Как считаем метрики производительности

В прошлой части мы рассказали, что провели исследование и выбрали 20 метрик документирования из 136. Метрик производительности среди них шесть.

В подсчете метрик есть два аспекта.

• Подсчет метрик по срезам. Выше мы рассказали, что это такое и почему нам это важно.
• Подсчет усредненных значений.

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

В таких случаях на выручку приходит перцентиль ^[3]. Это максимальное значение (в нашем случае — метрики), в которое укладывается указанный процент объектов. Например, 80-й перцентиль — это значение, которое не превышает 80% объектов выборки. В нашем случае таким значением было бы значение 1, так как его не превышают 83% объектов.

Здесь появляется третья плоскость — время, за которое мы считаем метрики. Почти все наши метрики считаются за 30 дней.

Метрики с разрезами мы считаем следующим образом:

• сначала все очереди вместе,
• затем делаем срез по очередям,
• потом детализируем: делаем срез по очередям с разрезом по всем типам задач.

Каждый следующий срез метрики уточняет предыдущий. Среднее значение по всем очередям, типам и статусам задач дает обобщенное представление. Затем мы считаем значение для отдельных очередей, чтобы понимать, как обстоят дела с технической, пользовательской или внутренней документацией. На последнем, самом детальном уровне, мы прорабатываем пару «очередь + тип и статус».

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

Количество закрытых задач

Как считаем: по количеству задач, которые закрыты в интервале [31 день назад; вчера].

Количество взятых в работу задач

Как считаем: по количеству задач, у которых начало работы находится в интервале [31 день назад; вчера].

Количество дней до взятия в работу

Как считаем:

1. Для каждой задачи, которая взята в работу в указанный период времени (start date в Трекере в интервале [31 день назад; вчера]), считаем количество полных дней, прошедших между постановкой (поле creation date) и началом выполнения задачи (поле start date).
2. Суммируем все значения, полученные на первом шаге.
3. Делим полученную сумму на количество задач, для которых мы делали первый пункт.

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

Количество дней на выполнение

Как считаем.

1. Для каждой задачи, которая завершена в указанный период времени (end date в Трекере в интервале [31 день назад; вчера]), считаем количество полных дней, прошедших между началом работы (поле start date) и выполнением задачи (поле end date).
2. Суммируем все значения, полученные на первом шаге.
3. Делим полученную сумму на количество задач, для которых мы делали первый пункт.

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

Количество задач без реакции более 14 дней

Как считаем: по количеству задач, в которых ничего не происходило более 14 дней. Определяется по полю updated в Трекере: значение поля должно быть меньше, чем «вчера−14 дней».

Технический долг

Как считаем: по количеству задач, у которых в Трекере установлен статус «Бэклог».

Техническая реализация подсчета метрик производительности

На верхнем уровне система подсчета метрик состоит из следующих компонентов и информационных связей.

Программа подсчета метрик, запускаемая по расписанию

Мы используем Nirvana ^[4] — универсальную вычислительную платформу. В ней формально описываем порядок запуска процессов. Вместе с внутренним планировщиком (scheduler) Nirvana заменяет нам набор bash-скриптов и cron.

Программа, написанная на Python, регулярно запускается и запрашивает необходимые для расчета метрик данные.

Система постановки задач

Данные для расчета метрик в нашем случае хранятся в Яндекс.Трекере. В качестве интерфейса к данным мы используем Python API Яндекс.Трекера — это обертка на HTTP API, которая позволяет быстрее и проще получать информацию в подходящих для дальнейшей обработки структурах данных.

Вы можете выбрать удобную для себя систему с подходящим API, например, Jira.

Система подготовки графиков

После подсчета метрик на основе данных из Яндекс.Трекера наша программа генерирует JSON-файлы и передает их во внутренний сервис Яндекс.Статистика для отрисовки графиков.

Вы можете использовать какую-нибудь JS-библиотеку, которая умеет строить графики. Обзор некоторых аналогичных решений есть на Хабре:

15 лучших JavaScript-библиотек ^[5]

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

Автор: docmain

Источник ^[6]