company_banner

Как мы считаем метрики разработки и поддержки документации. Доклад Яндекса

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



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


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


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


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


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


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

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


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


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


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


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


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


    Очереди


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



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


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


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


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


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



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


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


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


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



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



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


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


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



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


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

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


    В таких случаях на выручку приходит перцентиль. Это максимальное значение (в нашем случае — метрики), в которое укладывается указанный процент объектов. Например, 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 — универсальную вычислительную платформу. В ней формально описываем порядок запуска процессов. Вместе с внутренним планировщиком (scheduler) Nirvana заменяет нам набор bash-скриптов и cron.


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


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


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


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


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


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


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


    15 лучших JavaScript-библиотек


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

    Яндекс
    Как мы делаем Яндекс

    Комментарии 2

      +1
      Огонь, просто огонь! Спасибо. Как раз делаю ServiceDesc и самая большая проблема как раз в метрике. Много интересного.
        0
        Рассказывает Юрий Никулин

        Классно у вас сотрудника зовут)

        Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

        Самое читаемое