Гибкая разработка пользовательской документации

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

Приведенный способ работы с пользовательской документацией не уникален, а лишь иллюстрирует общий подход к гибкой разработке: программирование, тестирование, управление и прочие функциональные активности в гибкой разработке программного обеспечения работают по тем же принципам. Ранее эта мысль уже озвучивалась в заметке Усвоенные уроки одной кроссфункциональной команды разработки в разделе “Не накапливайте долги по разработке”, теперь рассмотрим ее подробнее.

Проблемы

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

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

Накопление долга

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

К чему это все приводит? Менеджер все свое внимание акцентирует на разработке функционала к желаемому сроку выпуска, но в итоге из-за аврала по документированию, неожиданно обнаруженного незадолго перед выпуском, вынужден или отложить выпуск, или выпускаться, жертвуя качеством. Техническому писателю, как понимаете, в этот момент совсем грустно: стресс, переработки и прочие беды. Ключевой момент здесь заключается в том, что в большинстве компаний технические писатели испытывают неравномерную нагрузку: вначале курят бамбук в ожидании, когда уже там эти программисты разродятся новой функциональностью, а потом в один миг получают сборку продукта с новым функционалом и вопрос менеджера: “Уф, наконец-то мы это сделали! Чуть-чуть, конечно, запоздали, но ничего: клиенту ведь обещали только завтра. Ты ведь успеешь, да?” Проблема низкой утилизации технических писателей обычно не волнует менеджера, даже если ему незнакома теория ограничений, но что делать со сдвигом сроков поставки и низким качеством продукции?

Патологию этого эффекта забавно изобразил Максим Дорофеев: посмотрите минутную вырезку из его видеоролика The Rise And Fall Of Waterfall (с мобильных устройств ролик недоступен).

Актуализация и тестирование

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

Проблема технического писателя заключается в исключительной сложности поиска тех мест документации, которые подлежат изменению в соответствии с измененной функциональностью продукта. Как быстро найти главу, в которую нужно добавить описание новой функции, чтобы пользователь быстро смог ее найти при необходимости? Как найти для удаления описание и все ссылки на устаревшую и исключенную из продукта функцию, чтобы не вводить пользователя в заблуждение? Чего уж говорить про случаи изменения поведения уже ранее существовавшей функции или связанное изменение нескольких функций? Ответ один: экспертно. На деле же при достаточном объеме документации это означает, что каждый раз все перечитывается от начала и до конца. А если надо выпускаться часто и быстро, как в случае облачных сервисов? Ага, можно просто застрелиться.

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

Планирование и отслеживание

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

Решение

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

Итеративность

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

Как обеспечить это свойство процесса?

Критерии готовности

Первая часть решения заключается наличии таких критериев готовности (Definition of Done) функциональности (реализованного требования), которые обязывают завершить все связанные работы: программирование, тестирование и документирование реализованного требования. Таким образом, функциональность считается готовой только тогда, когда она в том числе и описана в пользовательской документации. В итоге, минимизируется отставание всех связанных работ от программирования, что решает проблему накопления долгов. В идеале после завершения реализации каждой функциональности вы полностью готовы к отгрузке выпуска.

Стоит особенно отметить, что при этом технический писатель постоянно обеспечивается работой в рамках итерации. Он становится равноправным членом команды, как разработчики и тестировщики несет коллективную ответственность за общий результат команды. Менеджерам, которые беспокоятся за максимально полную утилизацию ресурсов, не стоит переживать по этому поводу: если технический писатель не является ресурсом ограничения, то есть на день работы разработчика приходится меньше дня его работы, то нужно просто задействовать его во всех проектах на необходимый процент загрузки – он будет работать по конкретному проекту практически каждый день, просто переключаясь по мере поступления работы. Самое важное, что работа ему будет поступать малыми порциями и часто, поэтому менеджеру остается только собрать необходимые метрики его работы в проекте, чтобы оптимально запланировать его участие в нем.

Визуализация работ

Определить требования к процессу – это половина, если не меньшая часть дела. Как обеспечить гарантию их выполнения, как не забывать их выполнять?

Традиционным решением, упрощающим следование гибким процессам, является визуализация работ с помощью доски задач. Критерии готовности требования, которое взяли в реализацию, нужно визуализировать таким образом, чтобы можно было легко увидеть: какие критерии уже выполнены, какие не выполнены, а какие находятся в процессе выполнения. Если на вашей доске задач напротив “бумажки” каждой пользовательской истории будут висеть “бумажки”, которые визуализируют все работы по реализации функциональности: разработка, тестирование, документирование и т.п. – вы вряд ли забудете поработать над каждой из них.

На снимке экрана ниже пример того, как это выглядит у нас.

Как это работает и выглядит, также можно посмотреть в прошлых заметках: Ежедневный Scrum с использованием интерактивной доски (см. видеоролик в конце заметки) и Планирование и отслеживание итеративной разработки с помощью Microsoft Project.

Трассируемость

На простой вопрос, часто возникающий при разработке пользовательской документации: “А мы вот это уже задокументировали?” – не всегда просто ответить сходу. Совсем тяжело бывает найти главу пользовательской документации, где описано реализованное требование. Слышал несколько раз и такой вопрос менеджера: “А вот эта глава актуальна? Кажется, в последнем выпуске мы эти функции сильно переделали. Пошли разбираться к разработчикам…”

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

Как обеспечить это свойство процесса?

Декомпозиция документации

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

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

На снимке экрана ниже пример завершенной реализации пользовательской истории (User Story), в рамках которой выполнялись задачи (Tasks) и создавались необходимые артефакты: тестовые случаи (Test Cases) и описания (Document Items). Трассировка до изменений исходных кодов (Changesets), замечаний по итогам рецензирования кода (Code Items), связанным проблемам (Issues) и дефектам (Bugs), а также прочим элементам управления конфигурацией продукта у нас также существует, но для упрощения примера не отображена.

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

Вот цитата из внутренней инструкции, созданной несколько лет назад:

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

1. Инкапсуляция. Документация формируется набором статей, каждая из которых независимо от остальных статей описывает свою определенную сторону: использования, развертывания, обслуживания и т.д. – программного кода. Вследствие этого содержательно статьи не ссылаются друг на друга. Иными словами, статья пишется таким образом, как будто всей остальной документации не существует.
2. Единственная ответственность. По возможности статья должна описывать только одну единственную атомарную сторону программного кода, а не содержать в себе описание нескольких независимых друг от друга описаний.
3. Декомпозиция. К примеру, при формировании требований к системе в общем требование к функции изменения объекта описывается как инициация действия изменения, а описание действий непосредственно по изменению объекта располагается в требованиях к функциям изменения определенных свойств объекта. Ровно таким же образом происходит разделение ответственности и слабая связанность между статьями, описывающими функцию изменения объекта: основная статья “Изменение” описывает, на какую кнопку и как правильно нужно нажать, чтобы инициировать действие изменение объекта, а вот уже дочерние статьи описывают, каким образом изменяются те или иные свойства объекта.
4. Композиция (никакого наследования) заключается в установлении иерархических связей между статьями, что исключает повторное документирование в дочерней статье действий, которые были описаны в родительской. К примеру, касательно приведенного выше примера: в описании изменения свойства объекта – название – не нужно снова повторять описание инициации действия по изменению всего объекта. Во-первых, статья описывает только то, как изменять название объекта (см. выше принцип единственной ответственности), во-вторых, в родительской статье это уже описано. Композиция представляется в виде одной отдельной статьи с содержанием: список названий и ссылок на статьи с указанием иерархии с помощью многоуровневых списков.

Впрочем, описывать детально это бессмысленно, попробуйте – через некоторое время вы сами ощутите этот эффект серебряной пули!

Автоматизация сборки документации

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

Идеальный вариант – это найти инструмент, который умеет синхронизировать описания (атомарные описания пользовательских историй) и пользовательскую документацию (финальный документ, файл справки, портал и прочие используемые вами форматы). И здесь конкретное решение зависит от того, какую систему управления жизненным циклом приложения (ALM, Application Lifecycle Management) вы используете. Но если вы, как и мы, используете Microsoft Team Foundation Server (далее – TFS), то с решением этой проблемы  вам поможет программа TeamSolutions TeamSpec, позволяющая в обе стороны синхронизировать документы Microsoft Word и рабочие элементы TFS.

Итог

Напомню ключевую идею: гибкие методологии применимы в любых функциональных областях отрасли разработки программного обеспечения – не только программировании, но и тестировании, документировании и управлении. Что там, вот мой друг и коллега пытается в течение уже нескольких лет доказать мне, что гибкие методологии в нашем правительстве могли бы значительно улучшить жизнь населения страны. Может быть, он прав?

Вот собственно и все. Я сознательно опустил все аспекты связанные с механическими действиями, специфическими для используемых нами продуктов: TFS, Word и TeamSpec – постаравшись донести только основную идею. Тем не менее, если вам это актуально и интересно, оставляйте комментарии, и, возможно, мне будет интересно потратить еще пару ночей, чтобы рассказать, как это работает.

---

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