Разработка технической документации
 

Doc-To-Help

Doc-To-Help

Doc-To-Help - это инструмент для технических писателей, позволяющий написать текст документации один раз, а затем сформировать на его основе множество вариантов, которые могут различаться форматами, комплектацией, целевой аудиторией и тому подобным. Такая методика подготовки документации называется Single source publishing, то есть публикация из единого источника. Для разработки технической документации существует множество других средств - Adobe RoboHelp, Help & Manual, DocBook и так далее. Важнейшим отличием Doc-To-Help является простота его использования - он не требует от пользователя знания какого-либо специального языка разметки и позволяет использовать в качестве редактора документов Microsoft Word.

Недостатки использования Microsoft Word для написания серьезной технической документации - известны. Прежде всего к ним можно отнести:

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

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

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

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

Разработчики Doc-To-Help постарались интегрировать свой продукт с Microsoft Word таким образом, чтобы устранить вышеперечисленные недостатки и одновременно сохранить преимущества. В итоге получился очень интересный продукт, прекрасно подходящий для решения практических задач.


Продукт Doc-To-Help построен как среда разработки справочных файлов. В нем создаются проекты, в проекты добавляются исходные файлы, файлы редактируются во внешнем редакторе и компилируются в один или несколько результирующих файлов справки.

Doc-To-Help поддерживает компиляцию файла справки в большинство общепринятых форматов: Microsoft Help 2.0, Microsoft Compiled HTML Help, JavaHelp, NetHelp (один или несколько обычных HTML-файлов), Microsoft WinHelp, а также в форматы PDF и Microsoft Word. Не поддерживаются FlashHelp и eBook (исполняемый Windows-файл, содержащий встроенную программу просмотра).

Doc-To-Help использует два формата исходных файлов - HTML и документы Microsoft Word. Разметка файлов осуществляется с помощью собственного языка разметки D2HML, представляющего собой предопределенный набор стилей. D2HML позволяет выполнить полную разметку файла справки - задать темы, ссылки, группы, задать переменные, определить условия условной компиляции и так далее.

Для редактирования документов Word в Doc-To-Help используется Microsoft Word, для редактирования HTML-файлов - Microsoft FrontPage или Adobe Dreamweaver. Во все эти редакторы Doc-To-Help встраивает собственную инструментальную панель, позволяющую выполнять всю разметку D2HML через удобный графический интерфейс. D2HML основан на стандартной HTML-разметке, поэтому в принципе исходные HTML-файлы можно также редактировать в любом другом текстовом редакторе. Однако в таких редакторах всю разметку D2HML придется выполнять вручную.


Интерфейс среды разработки Doc-To-Help 2008 построен в современной манере, с использованием технологии построения интерфейса Ribbon. Программа от этого только выиграла - панель инструментов получилась весьма лаконичной, интуитивно понятной, простой и удобной в использовании.

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

Справа отображается окно динамической справки. Следует отметить, что технология динамического отображения справки очень активно используется в Doc-To-Help 2008, что совершенно оправданно и весьма заметно ускоряет процесс обучения работы с программой. Например, все окна, открывающиеся при выборе инструментов на панели Microsoft Word, сразу отображают соответствующий раздел справки. В случае затруднений не нужно ждать, пока справка откроется, - она уже открыта. В то же время в дальнейшем такую справку легко скрыть и расширить рабочее пространство окна. Так же просто ее включить обратно.

Типичный процесс разработки файла справки в Doc-To-Help достаточно прост. Вы создаете новый проект, добавляете в него один или несколько исходных файлов, например в формате Microsoft Word. Выполняете предварительную настройку проекта, задаете необходимые переменные и параметры условной компиляции. Далее помещаете текст документации в исходные файлы и выполняете полную разметку файла справки - помечаете названия разделов, указываете темы оглавления, задаете ключевые слова, элементы глоссария и перекрестные ссылки. В итоге вы выбираете результирующий формат файла справки, указываете параметры его оформления, проводите компиляцию и получаете готовый файл.


Doc-To-Help обеспечивает возможность детальной настройки внешнего вида сгенерированных файлов справки. Для документов Word вы можете выбрать шаблон файла, для документов HTML - задать CSS-схему. Для каждого результирующего формата файла справки можно выбрать и настроить тему, задающую размещение окна, кнопок, цвет фона и так далее.


Возможность условной компиляции в Doc-To-Help позволяет элегантно решить ранее упоминавшуюся проблему профилирования файлов справки, когда из одного и того же набора исходных документов необходимо генерировать несколько вариантов документации, различающихся по содержанию. Для выбранного фрагмента текста можно задать параметры условной компиляции: платформу, целевой формат, значения атрибутов условной компиляции. При компиляции этот текст будет включен в результирующий файл справки в том и только в том случае, если заданные для него условия будут соответствовать условиям проведения компиляции. По умолчанию в проектах Doc-To-Help определен один атрибут условной компиляции - Build с возможными значениями Internal и Release, - но можно задать сколько угодно собственных атрибутов с произвольным набором значений.


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


Doc-To-Help содержит ряд возможностей, которые пригодятся непосредственно разработчикам программного обеспечения. Во-первых, Doc-To-Help поддерживает режим работы из командной строки, что может весьма пригодиться при организации автоматической сборки проекта. К сожалению, в документации к текущей версии Doc-To-Help 2008 (build 399) почему-то о данной особенности нет ни слова, поэтому довольно трудно разобраться, как эту возможность использовать. К счастью, описание режима работы командной строки есть в документации к Doc-To-Help 2007 (см. раздел Building Help Targets in Batch Mode). Во-вторых, Doc-To-Help имеет возможность интеграции с Microsoft Sandcastle, что может пригодиться при документировании библиотек классов. Наконец, Doc-To-Help позволяет конвертировать созданные файлы справки в XHTML и автоматически применять к ним заданную XSLT-трансформацию, то есть фактически проводить необходимую постобработку сгенерированного файла справки.


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


В качестве репозитория может использоваться обычная сетевая директория либо виртуальная директория, созданная на веб-сервере, поддерживающем технологию WebDAV. Специального серверного программного обеспечения устанавливать не требуется - всю работу по управлению совместной работой выполняет Doc-To-Help.


Программный продукт Doc-To-Help поставляется в двух различных вариантах - Doc-To-Help for Word и Doc-To-Help Enterprise. Версия for Word имеет ряд ограничений:


  • в качестве исходных документов не могут использоваться HTML-файлы;
  • не поддерживаются средства совместной работы;
  • нет конверторов RoboHelp HTML Converter и HTML Help Converter.

Пробная версия - общая для обоих вариантов. Она доступна на сайте разработчика и позволяет бесплатно ознакомиться с полной функциональностью продукта в течение 30 дней.


Возврат к списку


Страницы: 1 2 3 4 5 ... 7 След.
Это нравится:0Да/0Нет
writer

Doc-To-Help

Doc-To-Help - это инструмент для технических писателей, позволяющий написать текст документации один раз, а затем сформировать на его основе множество вариантов, которые могут различаться форматами, комплектацией, целевой аудиторией и тому подобным. Такая методика подготовки документации называется Single source publishing, то есть публикация из единого источника. Для разработки технической документации существует множество других средств - Adobe RoboHelp, Help & Manual, DocBook и так далее. Важнейшим отличием Doc-To-Help является простота его использования - он не требует от пользователя знания какого-либо специального языка разметки и позволяет использовать в качестве редактора документов Microsoft Word.
Это нравится:0Да/0Нет
writer
Появился он-лайн сервис Doc-To-Help  для написания технической документации. А вообще, кто-нибудь пробовал использовать Doc-To-Help для разработки документации?
Это нравится:0Да/0Нет
techwriter
Мы на него скоро переходим :)))
Это нравится:0Да/0Нет
writer
на он-лайн сервис? А почему так решили? В чем нашли его плюсы?
Это нравится:1Да/0Нет
techwriter
Цитата
writer пишет:
на он-лайн сервис? А почему так решили? В чем нашли его плюсы?
Не очень поняла про онлайн-сервис.
У нас просто должна быть интеграция с TFS, а он неплохо ее поддерживает. Протестировали конвертацию вордовой документации, довольно удобно. Ну, и плюс, что народ, привыкший работать в ворде, так и будет в нем работать. Народ, который привык работать с разметкой, будет работать с разметкой.
Это нравится:0Да/0Нет
writer
я так понял они запустили он-лайн сервис для разработки документации, хотя могу ошибаться

расскажите потом какие ощущения от работы с ним) по стоимости он дороговат конечно, порядка 52000 стоимость
Это нравится:0Да/0Нет
Виктор Фигурнов
Цитата
techwriter пишет: У нас просто должна быть интеграция с TFS, а он неплохо ее поддерживает. Протестировали конвертацию вордовой документации, довольно удобно.
Оба лидера в области Help Authoring Tools - Flare и Robohelp - предоставляют нативную интеграцию с TFS и аналогичными системами, включают удобный и хорошо настраиваемый импорт из Word, имеют намного больше возможностей и удобств, дают намного меньше геморроя и ограничений, чем Doc-To-Help.

Результаты недавнего опроса американских технических писателей 2014 User Assistance Tools Survey показали, что из 501 респондентов, тех, для кого Doc-To-Help имеет существенное значение для работы (5, 4 или 3 по пятибалльной шкале) - оказалось 7 человек. Для Madcap Flare - 131 человек, для Adobe Robohelp - 122 человека. Т.е. Doc-To-Help пользуется крайне малой популярностью среди технических писателей. И такая оценка, по моему мнению, полностью оправдана.
Цитата
techwriter пишет: Ну, и плюс, что народ, привыкший работать в ворде, так и будет в нем работать. Народ, который привык работать с разметкой, будет работать с разметкой.
Решение оставить Word имеет намного больше минусов чем плюсов.
Это нравится:0Да/0Нет
techwriter
Цитата
Виктор Фигурнов пишет:
Цитата
techwriter пишет: У нас просто должна быть интеграция с TFS, а он неплохо ее поддерживает. Протестировали конвертацию вордовой документации, довольно удобно.
Оба лидера в области Help Authoring Tools - Flare и Robohelp - предоставляют нативную интеграцию с TFS и аналогичными системами, включают удобный и хорошо настраиваемый импорт из Word, имеют намного больше возможностей и удобств, дают намного меньше геморроя и ограничений, чем Doc-To-Help.

Результаты недавнего опроса американских технических писателей 2014 User Assistance Tools Survey показали, что из 501 респондентов, тех, для кого Doc-To-Help имеет существенное значение для работы (5, 4 или 3 по пятибалльной шкале) - оказалось 7 человек. Для Madcap Flare - 131 человек, для Adobe Robohelp - 122 человека. Т.е. Doc-To-Help пользуется крайне малой популярностью среди технических писателей. И такая оценка, по моему мнению, полностью оправдана.
Цитата
techwriter пишет: Ну, и плюс, что народ, привыкший работать в ворде, так и будет в нем работать. Народ, который привык работать с разметкой, будет работать с разметкой.
Решение оставить Word имеет намного больше минусов чем плюсов.
Опять 25. Недавно обсуждалось. Что значит "оставить ворд"?
И какие возможность есть у Робохелпа и Мэдкэпа, которых нет у Doc-to-help?
При выборе средства разработки документации я ориентируюсь не на результаты опросов, а на то, что больше подходит в данном случае. Вот, и все.
Это нравится:0Да/0Нет
Виктор Фигурнов
Цитата
techwriter пишет:
Что значит "оставить ворд"?.
Если Word будет использоваться для чего-то кроме первоначальной подготовки текстов и формата документов для отправки текстов на рецензирование, то это породит множество проблем. Говорю по собственному печальному опыту.
Цитата
techwriter пишет:
И какие возможность есть у Робохелпа и Мэдкэпа, которых нет у Doc-to-help?
При выборе средства разработки документации я ориентируюсь не на результаты опросов, а на то, что больше подходит в данном случае. Вот, и все.
Как вы можете оценивать, что  больше подходит в данном случае, если даже не знаете, какие возможности есть у Robohelp и Flare, которых нет у Doc-to-help??? Да и вряд ли вообще работали с Robohelp и Flare, по крайней мере последних версий, иначе бы не задавали таких вопросов...

Сравнить эти системы можете здесь: http://hat-matrix.com/compare_hats/compare_up_to_four_tools_side-by-side.html

И надо учесть, что многие возможности, формально присутствующие в Doc-To-Help, Robohelp и Flare, в последних двух системах реализованы лучше, намного полнее и работают надёжнее, чем в  Doc-To-Help. Как написал один американец, с которым я пару лет назад обсуждал эту тему, Doc-To-Help does a great job, when it works properly... Мне кажется, что геморрой и танцы с бубном, неизбежные при использовании Doc-To-Help для чего-то кроме самых простых поделок, намного перевешивают его единственное достоинство - кажущуюся простоту освоения.. Но если это вам нравится - то хозяин барин...
Это нравится:0Да/0Нет
techwriter
Цитата
Виктор Фигурнов пишет:
Если Word будет использоваться для чего-то кроме первоначальной подготовки текстов и формата документов для отправки текстов на рецензирование, то это породит множество проблем. Говорю по собственному печальному опыту.
Повторю вопрос: что значит "Ворд будет использоваться для чего-то кроме первоначальной подготовки текстов? С чего вы решили, что он вообще будет использоваться? Он будет использован только на этапе перехода к другому формату, и все.
Страницы: 1 2 3 4 5 ... 7 След.