Внедрение технологии единого источника DITA в компании-разработчике ПО

    Здравствуйте! Меня зовут Елена Толмачева. В компании «ДоксВижн» я занимаюсь разработкой пользовательской документации.

    В последнее время для создания разного рода руководств по эксплуатации сложных программных систем все более популярным становится использование технологии единого источника, предполагающей повторное использование в разрабатываемом комплекте документов каких-либо текстов или изображений. Не так давно для разработки справок и печатных документов «ДоксВижн» мы стали применять данную технологию, и в этой статье я хочу поделиться полученным опытом.



    Почему мы выбрали технологию единого источника?


    Тем, кто знаком с компанией «ДоксВижн», известно, что основным разрабатываемым нами продуктом является платформа Docsvision, а помимо нее выпускается множество дополнительных приложений и модулей. Так как вспомогательные продукты предназначены для использования в составе платформы, при описании действий пользователя в документации часть текста нам приходилось дублировать: либо полностью, либо с незначительными изменениями. Такой подход (с учетом регулярного выпуска новых версий для всех продуктов) был очень трудоемок для технических писателей, т.к. громадный объем имеющихся описаний не позволял нам отслеживать изменения во всех повторяющихся разделах и оперативно вносить изменения сразу во множество документов.

    Были и другие сложности:

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

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

    Почему именно DITA


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

    • возможность выпуска документов в разных форматах (PDF, HTML5 и XHTML, Eclipse Help, TocJS, HTML Help, Java Help, ODЕ, RTF, troff),
    • жесткое структурирование разделов за счет типизированных «топиков» (concept, task, reference и др.)
    • возможность одновременной работы над проектом нескольких сотрудников.

    Мы выбрали технологию и приступили к составлению плана ее внедрения.

    Планирование


    В начале пути мы составили некий план, который по ходу дела, безусловно, пришлось корректировать. Здесь же я привожу набор этапов в строгой последовательности исполнения, который (по нашему мнению) является оптимальным для решения поставленной задачи. Обращаю внимание, что план подойдет при переходе на любую технологию единого источника (не только выбранную нами DITA).

    Этапы нашего плана таковы:
    1. Инструменты
    2. Стандартизация
    3. Дизайн
    4. Настройка
    5. Хранение
    6. Обучение

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

    Инструменты


    Новая технология подразумевает использование новых программных средств, поэтому на первом этапе внедрения нужно будет выбрать и приобрести некоторый софт. Как минимум, вам понадобится:
    • редактор для технических писателей (мы выбрали Oxygen XML Author)
    • инструмент для сборки документов из исходного формата в итоговый (мы выбрали DITA Open Toolkit, чтобы преобразовывать файлы формата XML в поставляемые форматы pdf и xhtml)
    • система хранения для исходных файлов и итоговых документов (мы выбрали TFS)

    При выборе редактора опираться стоит на удобство его использования, наличие функций для выполнения необходимых Вам задач и, конечно, стоимость профессиональной версии. Отмечу, что поддержка работы с DITA реализована почти во всех самых популярных редакторах для технических писателей (Oxygen XML Editor, XML Mind, DocBook, AuthorIt).

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

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

    Стандартизация


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

    Что потребуется стандартизировать:
    • типы документов, которые будут выпускаться по каждому из продуктов компании (руководство пользователя, руководство администратора и тд)
    • структуру документа для каждого из допустимых типов (титульный лист, введение, главы, разделы, список документов, приложения)
    • состав элементов для каждого элемента структуры (например, для титульного листа: логотип, название продукта, название системы, версия, тип документа)
    • перечень итоговых форматов (pdf, odt, xhtml и т.д.)
    • перечень локализаций (русскую, английскую и т.д.)
    • способ нумерации версий продукта и версий выпущенных документов по продукту

    Поясню, для чего нужен такой жесткий стандарт. В качестве примера рассмотрим титульный лист документации Docsvision, который в справке и печатном формате, хоть и выглядит в одном стиле, но различается по составу элементов и способу оформления. Например, в справке будет присутствовать описание назначения документа (которое в печатном формате располагается не на титульном листе, а в разделе «Введение»), поле поиска и оглавление. Обратите внимание, что остальной текст этих листов полностью совпадает, определяется стандартом и не зависит от стиля.


    Рис. 1. Пример состава элементов титульного листа

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

    Дизайн


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

    Желательно заранее ознакомить дизайнера с используемым в компании Справочником стилей, а если вдруг его нет (такое бывает часто), то хотя бы с сайтом компании.

    Макеты нужно подготовить:
    • для каждого из стандартизованных ранее форматов итоговых документов, например, отдельный набор картинок для pdf и отдельный набор картинок для xhtml-справки
    • для каждого их стандартизированных вариантов стилевого оформления (например, если в соответствии со стилем компании для продуктов используется разная цветовая гамма)
    • для каждого из стандартизированных языков (на иностранных языках будет использоваться другая терминология, программист может не знать, к примеру, перевода слова «Поиск» на французский язык)

    Подготовленные макеты следует согласовать с руководством компании и после этого можно перейти к этапу настройки.

    Настройка


    Как я уже предупреждала, для выполнения настройки, вероятно, придется подключать программистов различной специализации. Для сборки справок требуются знания СSS, и оптимальным будет привлечение специалиста по верстке. А для настройки вывода в печатные форматы только верстки может оказаться недостаточно. Например, для настройки используемого нами инструмента Dita Open Toolkit для сборки в формат PDF потребовался специалист, знакомый с XSLT преобразованиями.

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

    Пример того, как определить количество средств сборки документации, приведен на рисунке.


    Рис. 2. Варианты настройки программы для сборки документации

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

    Хранение


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


    Рис. 3. Принцип хранения файлов в технологии единого источника

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

    Структура хранения итоговых документов должна предусматривать:
    • раздельное хранение различных версий;
    • в рамках версии:
    — раздельное хранение для разных форматов;
    — раздельное хранение для разных локализаций.

    Обучение


    На заключительном этапе внедрения вам необходимо будет обучить коллег работе с новой технологией.

    В первую очередь, техническим писателям потребуется освоить новый редактор для написания текста.
    Вероятно, потребуется также изучить список тегов, которые будут обрабатываться программой для сборки документации. Например, в «ДоксВижн» мы используем теги спецификации DITA.
    Если до перехода на использование технологии единого источника часть текста копировалась, теперь его можно и нужно будет научиться использовать повторно. Плюс к тому, коллег нужно ознакомить с новыми структурами хранения данных и внимательно следить за тем, чтобы этот стандарт всеми соблюдался.

    Что в итоге


    Если внедрение будет успешным, качество разрабатываемой документации значительно повысится, а затраты на ее производство уменьшатся. Технические писатели будут получать больше удовольствия от своей работы, а их руководители – положительные отклики от партнеров.

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

    Для информации: много материалов по DITA собрано на сайте DITA Writer, и там же есть список литературы.

    Надеюсь, этот материал окажется для вас полезным и поможет перейти на новую технологию быстро и безболезненно!
    ДоксВижн 46,21
    Компания
    Поделиться публикацией
    Похожие публикации
    Комментарии 11
      0
      жутко заинтриговали, но ничего не понятно. Сейчас как раз присматриваюсь к подобным вещам — есть проект, в котором надо привести в порядок документацию, на два языка и четыре роли пользователей. Вот похоже что то, что Вы описываете дюже смахивает на то, что я ищу. Может посоветуете, где можно попредметнее посмотреть, что бы даже немножко пощупать на конкретных кейсах.
        0
        Вы правы, единый источник для вас – идеальное решение! В случае с DITA реализация ролевой документации на одном языке будет выглядеть примерно так: каждый раздел должен быть написал в отдельном файле (топике), внутри файла текст каждой роли выделяется тегом c определенным ID, а при сборке настраивается фильтрация по тегам с этим ID. 4 роли – 4 фильтра. Аналогичным образом можно настроить фильтры и для локализаций, но тут возникают сложности у переводчиков. По этой причине, как правило, локализованные файлы хранят отдельно.

        К сожалению, узнать на практике, как это работает, негде. Книг на русском языке нет, только на английском.
          0
          Книг на русском языке нет, только на английском.


          Осмелюсь напомнить — мы на хабре. Может включите список литературы в статью — имхо она от этого только выиграет.
            0
            Спасибо за рекомендацию, добавила в статью ссылку на литературу.
          0
          То, что Вам нужно будет построено либо на LaTeX либо на XML.

          Из XML стандартов есть два, подходящих для технической документации (как для софта так и для железа): DocBook и DITA. Лично мне больше импонирует DITA, но DocBook имхо проще на старте.

          XML (опять же, имхо) проще для технических писателей. Особенно, если пользоваться хорошими CSS-based XML редакторами. К списку таких редакторов, которые приводит автор я бы еще добавил Arbortext. Но мой выбор здесь — oXygen XML Author, так же как и у автора статьи. Минус один — они все очень недешевы.

          Кстати, рекомендую посмотреть:
          habrahabr.ru/post/212881/
          habrahabr.ru/company/mirantis_openstack/blog/190624/

          А помимо хранения в репозитарии еще потребуется CI: сборка, публикации и тестирование. Разработка документации это вам не просто так :)
            0
            спасибо, пошел смотреть.
          0
          Вы правы, единый источник для вас – идеальное решение! В случае с DITA реализация ролевой документации на одном языке будет выглядеть примерно так: каждый раздел должен быть написал в отдельном файле (топике), внутри файла текст каждой роли выделяется тегом c определенным ID, а при сборке настраивается фильтрация по тегам с этим ID. 4 роли – 4 фильтра. Аналогичным образом можно настроить фильтры и для локализаций, но тут возникают сложности у переводчиков. По этой причине, как правило, локализованные файлы хранят отдельно.

          К сожалению, узнать на практике, как это работает, негде. Книг на русском языке нет, только на английском.
            0
            А почему бы не прибегнуть к полноценному решению, покрывающему все циклы разработки документации? например, это? Они предлагают, как клиентское решение, так и полноценное Web CMS и даже Cloud. Можно бесплатно получить тестовый аккаунт в CLoud и оценить все самим. При этом вам понадобится только два инструмента — браузер и Java (если она еще у вас не установлена). Из прелестей:
            — весь цикл разработки документации от создания топиков до их публикации во все известные форматы покрыт одним приложением
            — широченный комплекс функциональностей: ревью, переводы (с интеграцией с известными TMS, такими как XTM), брэнчинг и возможность создания снэпшотов (так называемый бэкап всей документации с возможностью внесения точечных изменений), context sensetive reuse (модная штука на базе keyref подхода из DITA 1.2), metadata extraction, и бог знает че еще там есть
            — встроенный редактор oXygen Author (лидер на мировом рынке XML редакторов)
            — встроенные publication engines: старый добрый DITA Open Toolkit и xmlMind DITA Converter(работает в сотню раз быстрее чем тулкит)
            — вполне дружелюбный интерфейс
            — всем заинтересованным бесплатная демонстрация возможностей
              0
              Забыл добавить — product Manager у них русскоговорящй. Намного упростит коммуникацию для интересующихся из стран бывшего СНГ.
                0
                К сожалению, никакое, даже самое лучшее решение не избавит вас от этапов стандартизации, дизайна, настройки и обучения. Любое решение надо настраивать под себя. У тулкита есть огромное преимущество — он бесплатный! А стоимость предложенной CMS, насколько я знаю, весьма высока.
              0
              По доброй традиции хаба «Клиентская оптимизация» поинтересуюсь:
              — автор, вам известно значение термина, давшего название упомянутому хабу?
              — какое отношение этот топик имеет к предметной области, описываемой этим термином?

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

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