28 декабря 2020
Управление документацией на проект как видом данных
В отличие, например, от клиентских данных, документация на проекты в IT-сфере представляет собой накопленные знания, зачастую достаточно объемные, и привязанные к той или иной версии проекта. Кроме того, документация может отличаться по своей форме в зависимости от особенностей проекта и от задач, которые она решает. Учитывая все это, управление документацией требует особого подхода. Причем, решения класса Master Data Management не приспособлены для этого, но могут быть использованы некоторые приемы концепции MDM.

Рассмотрим ряд нюансов формирования подхода к документированию и дадим краткий обзор инструментов.
На что обращать внимание
Если вы только начинаете формировать подход к управлению документацией, или перестраиваете бизнес-процессы документирования, то следует учитывать следующие нюансы:
  1. Рекомендуем определиться со всеми задачами документирования заранее, в долгосрочной перспективе. Это необходимо для того, чтобы выбирать инструменты и методы работы с учетом будущих задач, так как только одна новая задача может полностью изменить все бизнес-процессы и, соответственно, подход к работе. Например, документация на платформу Юнидата исторически делалась только для русского языка, и теперь, когда мы начали формировать документацию на английском, нам предстоит выбрать новые инструменты документирования, в которых можно будет работать с двумя языками, но при этом сохранять удобные функции текущих инструментов.
  2. Спросите заказчиков. Если у вас есть несколько заказчиков, использующих ваш проект, есть смысл собрать обратную связь чтобы понять в какой форме им была бы удобна документация. Это может помочь подтвердить или скорректировать гипотезу насчет выстраиваемых процессов документирования. Старайтесь найти боли заказчика, его потребности, так как прямые слова могут не отражать всей сути проблемы.
  3. Рекомендуем выстраивать как можно более простую структуру контента. Избегайте вложенности заголовков внутри документа глубже 3 уровня; используйте чек-листы и обзорные статьи, в которых можно ссылаться на разные части документов.
  4. Если у вас есть продуктовая документация, то рекомендуем выстраивать процессы документирования вокруг нее. Например, при необходимости создавать продуктовую документацию и документацию по ГОСТ, лучшим выбором может стать упор на продуктовую документацию и дальнейшая конвертация документов под оформление ГОСТ.
  5. Внедряйте и используйте руководство по стилям. Стандартизируйте инструкции и описания. Особенно, если документация планируется к переводу.
  6. Расставляйте приоритеты. Отдавайте приоритет такому контенту, который действительно нужен сейчас. Понятные приоритеты для всего будущего контента помогут выстроить процесс более грамотно.
  7. Скорее всего, проект будет использовать несколько видов документации. Из этого вытекает следующее:
  8. Для разных видов могут понадобиться разные инструменты (зависит от требований к каждому виду). Если на проекте есть технический писатель, то с этим будет проще работать.
  9. Стиль изложения может отличаться для разных видов документации. В идеальном случае за этим должен следить технический писатель.
  10. Качество документации может обеспечиваться только в ручном режиме. Проверку могут осуществлять инженеры тестирования (например, в процессе тестирования релиза можно параллельно сверяться с документацией на релиз). Также автор может проверять сам себя, перечитывая документацию через некоторое время. Если над документацией работает несколько человек, то возможна перекрестная проверка, либо проверка лидером группы. Также можно использовать схему обратной связи от пользователей (клиентов или сотрудников других подразделений).
  11. Рекомендуем учитывать возможность совместного авторства на этапе выбора инструмента документирования, так как не все инструменты одинаково эффективно к этому приспособлены. Наиболее удобными схемами совместного авторства являются: совместный доступ к одному файлу с возможностью комментирования (MS Word и аналоги) и распределение контента по авторам (базы знаний, технологии единого источника).
  12. Схемы работы по бизнес-процессам (с согласованием изменений и т. д.) рекомендуются только в исключительных случаях.
Какие виды документации бывают
Важно понимать, что документация может быть разных видов, каждый из которых будет накладывать свои особенности. Чтобы было проще классифицировать инструменты управления документацией выделим несколько видов:
  • Документация исходного кода. Содержит информацию о модулях, отдельных классах, отношениях между классами и т. д. Зачастую, документация используется внутри команды проекта.
  • Документация API. Содержит информацию о назначении API, описание запросов (включая передаваемые параметры, примеры и т. д.). Предназначена для внешних пользователей, желающих интегрироваться с API.
  • Продуктовая документация. Описывает работу с продуктом с точки зрения всех возможных пользователей. Как правило, представляет собой набор различных документов. Например, руководства пользователя и администратора, руководства по установке, инструкции по настройке и обслуживанию. Такая документация должна объяснять сложные вещи простым языком и иметь высокое качество текста.
  • Проектная документация. Представляет собой отчетную документацию, отражающую особенности индивидуального проекта. Это может быть готовый продукт, индивидуально доработанный под заказчика, или выполненный проект под заказ. Зачастую главная цель проектной документации:
            - соответствовать определенным стандартам/требованиям заказчика;
            - снизить риски исполнителя и заказчика;
            - зафиксировать планы работ и технические решения.

  • Эксплуатационная и административная документация. Документы содержат информацию:
            - по обслуживанию готового проекта;
            - по регламентированию работы с проектом, в том числе по распределению пользователей на группы и описанию обязанностей для каждой группы. Отражает бизнес-процессы заказчика.

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

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

По мере развития любого проекта к документации предъявляются определенные требования. Эти требования могут трансформироваться со временем, расширяться или, наоборот, сужаться. На требования к документации влияет как суть проекта, так и политика менеджмента. Таким образом, документация может быть очень разной, и сочетать в себе сразу несколько видов.

Виды инструментов для документирования
Инструменты также можно разделить на несколько больших групп:
  • Текстовые редакторы;
  • Базы знаний;
  • Инструменты, использующие принцип единого источника;
  • Генераторы документации из исходного кода;
  • Инструменты памяти перевода;
  • Системы управления версиями;
Текстовые редакторы, предназначенные для создания текста, различаются между собой по набору вспомогательных функций. Например, MS Word позволяет использовать стили, интегрироваться с другими инструментами пакета MS Office, верстать документы, работать совместно (как через одновременный доступ в облаке, так и через режим рецензирования) и т.д. В то же время Atom не имеет этих возможностей, но содержит подсветку синтаксиса различных языков, интеграцию с Git и плагины, расширяющие функциональность. Текстовые редакторы используются для всех видов документации, кроме описания исходного кода. Минусы текстовых редакторов проявляются в следующих случаях:
  • Когда заметно увеличивается объем контента, который нужно описывать и затем поддерживать.
  • Когда возникает необходимость переводить документацию на другие языки и одновременно поддерживать актуальность оригинала и переводов.
  • При частых релизах проекта.
  • Когда есть несколько проектов, имеющих заметные сходства между собой.
Базы знаний предназначены для хранения всех накопленных знаний по теме (в нашем случае – о проекте), которые распределены по отдельным страницам. Вне зависимости от формы базы знаний, будь то вики-система или статический сайт, контент выстраивается по иерархической схеме, а кроссылки ускоряют переход между страницами. Также базы знаний используют из-за возможностей интеграции с другими системами и возможностей использовать медиа (прикреплять файлы, вставлять ссылки на видео и т.д.). Базы знаний используются для всех видов документации как наиболее универсальное средство. Минусы баз знаний:
  • Сложности при экспорте в формат печатных документов: типовой шаблон может не подходить по требованиям проекта (особенно актуально для документации по ГОСТ); многие базы знаний не позволяют собрать из набора страниц документ для экспорта; кроссылки и прикрепленный контент необходимо редактировать и т.д.
  • Не все базы знаний могут поддерживать наборы документации для разных версий проекта.
  • Нет встроенной интеграции с инструментами памяти перевода.
Принцип единого источника предполагает, что есть один инструмент, в котором контент содержится в виде топиков (небольших статей). Каждый топик пишется отдельно, а потом из набора топиков собираются необходимые документы разных форматов. Из инструментов, использующих этот принцип, можно выделить Dita или LaTeX. Каждый инструмент имеет свой набор дополнительных возможностей, таких как механизмы работы с перекрестными ссылками, вставка готовых блоков контента, использование лексем как переменные и т.д. Модульный подход, помимо плюсов, имеет и ряд минусов:
  • Сложный и длительный процесс интеграции инструментов.
  • Файлы топиков представляют собой текст со специальными командами языка разметки. К автору документации будут предъявляться дополнительные требования знания языка. Обучение также занимает время. Существуют решения с WYSIWYG, далеко не все из них удачны.
  • Традиционно слабые возможности дизайна выходного формата. Создание новых шаблонов – сложный процесс с множеством нюансов.
  • Многие инструменты имеют открытый исходный код, что, с одной стороны, позволяет гибко настраивать инструмент под свои задачи, а с другой стороны превращают многие задачи по настройке в трудоемкий процесс.
Такие инструменты, как Doxygen, позволяют генерировать документацию из исходного кода. Doxygen вычитывает заданный объем файлов исходного кода, и создает на основе полученной информации интерактивный HTML, в котором можно отследить отношения между классами, просмотреть комментарии к классам, отобразить графы наследования и т.д. Также можно сохранять документацию в формате XML, PDF, RTF и т.д. Минусы:
  • Поддерживаются не все языки программирования.
  • Внешний вид HTML необходимо дорабатывать.
  • Не у всех инструментов есть гибкие настройки. Например, Doxygen представляет собой монолитное ядро, и любые настройки возможны лишь при изменении исходного проекта.
  • Для решения прикладных задач возможно понадобится выстраивать конвейер (пример: Doxygen > конвертация в REST любым сервисом > Sphinx).
Инструменты памяти перевода предназначены для автоматизации процесса перевода. Весь текст для перевода разбивается на лексемы (в виде терминов, устойчивых выражений и т.д.). Перевод каждой лексемы хранится в базе данных, и подставляется автоматически везде, где встречается, что значительно ускоряет работу. Минусы:
  • Высокая цена ошибки, так как она может распространиться по всему документу.
  • Сложности интеграции с инструментами документирования. Необходимо искать собственные решения для интеграции.
  • Неудобства перевода файлов с языком разметки (XML или разметка Latex).
Системы управления версиями позволяют хранить и использовать несколько версий одного документа. В документировании системы управления версиями хорошо интегрируются с базами знаний, инструментами единого источника и некоторыми текстовыми редакторами (например, редакторами с выходным форматом данных XML или MD). Минусы использования систем управления версиями:
  • Не все инструменты документирования удачно интегрируются.
  • Не все форматы файлов вычитываются системами управления. Например, для MS Word можно только управлять файлами целиком, либо управлять через конвертацию в промежуточные форматы.
Итог
Управление документацией представляет собой сложный многоаспектный процесс (как и, собственно, управление данными), поэтому необходимо к нему подходить серьезно. Чтобы построить схему управления документацией требуется проанализировать все потенциальные варианты, собирать требования к документированию, спрогнозировать будущие потребности.

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