Применение продуктов MadCap Software на отечественном софтверном производстве на примере компании АСКОН

23.06.2016

Сегодня мы публикуем рассказ одного из наших клиентов – Анастасии Тян, технического писателя из компании АСКОН – об их опыте использования продукта MadCap Flare и Lingo. Этими продуктами в компании начали пользоваться ещё до того, как компания ПроТекст стала партнёром MadCap Software, и пользуется по сей день, не забывая обновлять их до актуальных версий, чтобы задействовать все преимущества программного обеспечения.

АСКОН — крупнейший российский разработчик инженерного программного обеспечения и интегратор в сфере автоматизации проектной и производственной деятельности. В продуктах компании воплощены достижения отечественной математической школы, 26-летний опыт создания САПР и глубокая экспертиза в области проектирования и управления инженерными данными в машиностроении и строительстве. Программное обеспечение АСКОН используют свыше 9000 промышленных предприятий и проектных организаций в России и за рубежом.

В АСКОН MadCap Flare используется для написания и оформления справочной документации к новым продуктам —  к системе информационного моделирования Renga Architecture (справка) и системе управления проектированием Pilot-ICE (справка).

Современная справка для новых продуктов

Много лет АСКОН использует  Adobe® FrameMaker®  для создания PDF-документации и с помощью плагина Mif2Go генерирует CHM-справку из проектов FrameMaker®.

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

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

Оценка программных продуктов для технической коммуникации вскоре привела нас к MadCap Flare.

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

Создание контента

Сегодня два продукта АСКОН сопровождаются документацией, созданной во Flare: Renga Architecture – 3D CAD для архитекторов, и Pilot-ICE  –  клиент-серверная система для управления проектной организацией.

С помощью единого источника MadCap Flare мы выпускаем Help в HTML5 и PDF-документацию для всех приложений системы Pilot. А приложений Pilot на данный момент насчитывается 5. Мы создаём HTML5 Help для каждого из них, чтобы они вызывались у пользователей локально. Вместе с тем, вы создаём онлайн-справку для всей системы целиком. Из-за того, что в приложениях есть одинаковые функции, мы можем использовать контент много раз.

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

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

Continuous Delivery

Разработка программного обеспечения в наших командах идёт на основе практики Сontinuous Delivery. И мы решили включить контент, созданный с помощью Flare в этот процесс.

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

А далее поступили так. Файлы, созданные писателем в MadCap Flare, а также созданные переводчиком с помощью MadCap Lingo, размещаются в системе управления версиями Mercurial.

После коммита в Mercurial новая версия справки собирается на сервере с помощью TeamCity и Flare, а затем отправляется в инсталлятор.

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

Использование преимуществ стандарта

Мы также постарались извлечь выгоду от родной XML-архитектуры Flare c поддержкой HTML.

Например, система Pilot-ICE обновляется практически каждый месяц и в ней есть раздел “Что нового?”, который включён в проект Flare. С помощью простого текстового редактора любой член команды может добавить туда информацию.

Поскольку люди, у которых даже не установлен Flare, могут добавлять информацию об обновлениях с помощью любого текстового редактора, документация всегда актуальна и обновляется вместе с продуктом.

Кроме того, мы используем онлайн-сервис Яндекс.Метрика для анализа трафика онлайн-справки и интересов клиентов. Код от Яндекс.Метрики вставляется на  Master Page проекта в MadCap Flare. А затем Master Page используется при сборке онлайн-справки.

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

Дополнительные плюсы

С помощью Flare можно быстро и просто создать раскрывающийся текст (drop-down text). Так, один раздел может содержать в себе массу информации, без перегрузки информацией. В результате пользователю нужно просто развернуть текст, чтобы получить нужную информацию. Я была уверена, что раскрывающийся текст доступен только для HTML5, но обнаружила, что он работает и в CHM-справке.  Поэтому обе сборки теперь выглядят более привлекательными, чем раньше.

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

Также не составит труда добавить в проект мультимедиа-контент. Например, в Renga Architecture мы решили показывать, как работают инструменты, с помощью анимационной графики. Это оказалось очень просто и очень эффективно. Я делаю гифку, затем вставляю её, как картинку.

А в новых версиях программы появилось слайд-шоу, с которым тоже можно сделать справку привлекательнее, но не перегружать картинками.

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

С помощью MadCap мы добились большого успеха при разработке документации для наших систем Renga Architecture и Pilot-ICE. И мы продолжаем улучшать нашу документацию с MadCap.

Тэги: Flare, MadCap, единый источник, инструменты, опыт