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

Editor's Notes

• #7: На ретроспективе я поднял эти проблемы и предложил команде совместно определить процесс создания документации таким образом, чтобы создание и модификация документации к продукту стало прогнозируемо. В итоге, мы изменили процесс разработки пользовательской документации, наделив его следующими свойствами: итеративность и трассируемость.ИтеративностьИсключить накопление долга и обеспечить возможность планирования и отслеживания работ по документированию можно с помощью включения этих работ в общий процесс итеративной разработки. Таким образом будет обеспечено согласованное инкрементальное наращивание и функциональности продукта, и его описания. Как следствие, появление долга по документированию принципиально исключается, а весь процесс разработки в целом получается прогнозируемым.ТрассируемостьНа простой вопрос, часто возникающий при разработке пользовательской документации: “А мы вот это уже задокументировали?” – не всегда просто ответить сходу. Совсем тяжело бывает найти главу пользовательской документации, где описано реализованное требование. Слышал несколько раз и такой вопрос менеджера: “А вот эта глава актуальна? Кажется, в последнем выпуске мы эти функции сильно переделали. Пошли разбираться к разработчикам…”Соответственно, нужен механизм, который позволит быстро отвечать на все эти вопросы, исключая необходимость полагаться на память людей, которая не идеальна. Как следствие, будут решены проблемы актуализации и тестирования документации.
• #8: Как обеспечить свойство процесса – итеративность?Критерии готовностиПервая часть решения заключается наличии таких критериев готовности (DefinitionofDone) функциональности (реализованного требования), которые обязывают завершить все связанные работы: программирование, тестирование и документирование реализованного требования. Таким образом, функциональность считается готовой только тогда, когда она в том числе и описана в пользовательской документации. В итоге, минимизируется отставание всех связанных работ от программирования, что решает проблему накопления долгов. В идеале после завершения реализации каждой функциональности вы полностью готовы к отгрузке выпуска.Стоит особенно отметить, что при этом технический писатель постоянно обеспечивается работой в рамках итерации. Он становится равноправным членом команды, как разработчики и тестировщики несет коллективную ответственность за общий результат команды. Менеджерам, которые беспокоятся за максимально полную утилизацию ресурсов, не стоит переживать по этому поводу: если технический писатель не является ресурсом ограничения, то есть на день работы разработчика приходится меньше дня его работы, то нужно просто задействовать его во всех проектах на необходимый процент загрузки – он будет работать по конкретному проекту практически каждый день, просто переключаясь по мере поступления работы. Самое важное, что работа ему будет поступать малыми порциями и часто, поэтому менеджеру остается только собрать необходимые метрики его работы в проекте, чтобы оптимально запланировать его участие в нем.Визуализация работОпределить требования к процессу – это половина, если не меньшая часть дела. Как обеспечить гарантию их выполнения, как не забывать их выполнять?Традиционным решением, упрощающим следование гибким процессам, является визуализация работ с помощью доски задач. Критерии готовности требования, которое взяли в реализацию, нужно визуализировать таким образом, чтобы можно было легко увидеть: какие критерии уже выполнены, какие не выполнены, а какие находятся в процессе выполнения. Если на вашей доске задач напротив “бумажки” каждой пользовательской истории будут висеть “бумажки”, которые визуализируют все работы по реализации функциональности: разработка, тестирование, документирование и т.п. – вы вряд ли забудете поработать над каждой из них.
• #12: Как обеспечить свойство процесса – трассируемость?Декомпозиция документацииАктуализация и тестирование документации являются затратными работами, потому что пользовательская документация представляет собой монолитный большой артефакт, внутри которого каким-то непредсказуемым образом разбросано описание реализованных пользовательских историй.А что если декомпозировать документацию на отдельные детали, каждая из которых представляет атомарную автономную документацию конкретного реализованного требования? Тогда станет возможной двусторонняя навигация: от конкретной пользовательской истории к ее описанию в пользовательской документации и обратно от конкретной части документации к тому требованию, которое было реализовано и породило данное описание. В итоге, сценарий обновления документации превращается в механическую работы: найти и добавить в пользовательскую документацию описания требований, реализованных за время работы над последним выпуском, обновить в пользовательской документации описания измененных требований, удалить описания исключенных из выпуска функций.Автоматизация сборки документацииОсновные идеи, описанные выше, впервые посетили воспаленный мозг одного менеджера и были опробованы им в команде еще несколько лет назад. Единственное, что омрачало тогда все это действо: незначительные, но никак не поддающиеся исключению посредством автоматизации, трудозатраты по сборке документации. Конечно, при таком подходе уже не нужно было пытать программистов, что же изменилось в последней версии продукта, чтобы найти изменения, которые необходимо перенести в финальный документ пользовательской документации: просто выбираешь все описания, созданные или измененные в рамках подготовки последнего выпуска. К слову, это самые значительные трудозатраты при сборке пользовательской документации. Но все же остается достаточно много работы по поиску в финальном документе мест, которые нужно заменить на текст из подготовленных заранее описаний. Сейчас тот менеджер нашел таблетку и от этой головной боли.Идеальный вариант – это найти инструмент, который умеет синхронизировать описания (атомарные описания пользовательских историй) и пользовательскую документацию (финальный документ, файл справки, портал и прочие используемые вами форматы). И здесь конкретное решение зависит от того, какую систему управления жизненным циклом приложения (ALM, ApplicationLifecycleManagement) вы используете. Но если вы, как и мы, используете Microsoft Team FoundationServer (далее – TFS), то с решением этой проблемы  вам поможет программа TeamSolutionsTeamSpec, позволяющая в обе стороны синхронизировать документы MicrosoftWord и рабочие элементы TFS.