После удачного приобретения программы для документирования Dr.Explain я начал создавать файлы помощи для всех своих проектов, в том числе для ClassExplorer – “Справочник разработчика”. И тут мне вдруг подумалось: а не заменил ли мне мой новый инструмент создаваемую программу? Не превратится ли мой новый помощник в убийцу данного проекта?
Dr.Explain vs ClassExplorer
Из всех возможностей, которые имеются у программы Dr.Explain, в данной статье разберём только одну – создание базы знаний, ведь именно так позиционируется проект “Справочник разработчика” или ClassExplorer.
При создании документа в Dr.Explain можно выбрать шаблон, что может сэкономить время и обеспечить полноту описания. Особенно это актуально при ведении документации согласно ГОСТ. Приятным бонусом программы является встроенная поддержка ГОСТ 34, в котором указаны основные правила оформления документации для ПО. Но в нашем случае это не нужно, жмет на кнопку “Создать локальный проект” (1).
Главная форма
Рабочая область Dr.Explain разделена на две части: слева находится дерево разделов (страниц), по середине – WYSIWYG редактор, по своей функциональности сравнимый с компонентом TdbRichEdit, который имеется в распоряжении разработчиков, использующих My Visual Database.
Рабочая область ClassExplorer организована иначе: минималистичный тулбар со строкой поиска, а ниже несколько вкладок, на которых расположены древовидные или линейные списки по категориям страниц. А для отображения самой страницы потребуется задействовать поиск или кликать по кнопке открытия примера. А чтобы изменить данные придется использовать кнопки на тулбаре и формы редактирования.
Дерево страниц
Стоит внимательней присмотреться к дереву Dr.Eхplain. На первый взгляд дерево как дерево. Всего одно, но хорошее (с). Кроме пользовательских страниц, оно содержит несколько служебных:
- Страница документа (корневая страница)
- Начальная страница
- Оглавление
Начальная страница – это элемент, который обычно используется при создании файла помощи – при открытии файла без указания раздела, открывается именно начальная страница. В других форматах вывода это может быть обложка документа. Но для каждой страницы можно по желанию настроить необходимость экспорта в тот или иной формат:
Оглавление – очень полезный элемент при создании печатного варианта документации. Dr.Explain создаёт оглавление автоматически, не требуя дополнительных действий для обновления оглавления после изменения содержания. При этом имеется возможность настройки как внешнего вида, так и глубины построения дерева оглавления. Как автор нескольких руководств и обучающих пособий я высоко оценил эту возможность.
Страница документа отображает статистику и содержит инструменты для экспорта данных (в нашем случае – для создания информационной системы) в различные форматы.
Статистика готовности - это важный элемент планирования производства. И это очень важный момент профессионального подхода к ведению документации: создавая структуру документа вы одновременно создаёте (или корректируете) план работ, а готовность отображается специальным графическим индикатором. Это возможно благодаря тому, что каждый раздел дерева имеет специальный статус готовности с цветовым обозначением.
Здесь же отображается путь к экспортируемым данным, который запоминается после операции экспорта – на мой взгляд очень свежее интерфейсное решение.
Редактирование структуры дерева Dr.Explain максимально удобно, так как имеется несколько альтернативных возможностей для этого: кнопки на панели инструментов, горячие клавиши и перетаскивание мышкой.
Деревья ClassExplorer выглядят скромней, без дополнительных графических элементов. Редактирование структуры не такое лёгкое: для перемещения ветки придётся использовать форму редактирования. Единственное, что утешает в данной ситуации, что структура данного справочника меняется редко.
Для получения статистики ClassExplorer нужно открыть форму “О программе”, где можно увидеть число элементов по категориям.
Редактор
Для создания страниц в Dr.Explain имеется богатый набор инструментов: управление стилем текста, характеристиками шрифта, выравнивание и создание списков.
Инструмент для вставки изображений настолько крут, что достоин отдельного рассказа, а пока лишь упомяну, что он способен творить чудеса: в процессе аннотирования картинки он распознает расположение элементов пользовательского интерфейса и их тип, в том числе для приложений, написанных на Java.
Внутренние гиперссылки – это то, чего не хватает ClassExplorer (и никогда у него не появятся, так как автор My Visual Database приостановил развитие данного фреймворка). Зато они есть у Dr.Explorer, причем благодаря продуманным алгоритмам, при совпадении текста и названия раздела связывание возможно буквально в один клик.
На страницу Dr.Explain может вставлять что угодно: таблицы, видео, произвольный HTML-код.
Есть уникальный механизм макроподстановок: в документе можно создать текстовые переменные, вставлять их в текст, а затем одним махом менять значение этой переменной. Данная возможность пригодится, если у вас несколько типовых проектов с похожим описанием, которое отличается только отдельными ключевыми словами, которые можно вынести в переменные. У меня такие проекты точно имеются.
Что же может предложить в противовес ClassExplorer? Только две фишки:
Поиск данных
Информационные системы, создаваемые Dr.Explain в форматах HTML или CHM, имеют встроенную систему поиска: по ключевым словам и по вхождению текста. Первая отличается скоростью, но для своей работы требует со стороны автора дополнительных усилий: для каждой страницы нужно сформировать список ключевых слов. Второй вариант скоростью не блещет, зато отличается полнотой охвата.
Итоги
Вполне очевидно, что Dr.Explain – это прежде всего редактор, с помощью которого можно создать информационную систему: в виде набора HTML-файлов или файла CHM. А ClassExplorer – это информационная система с возможностью редактирования данных. Несмотря на то, что Dr.Explain обладает более богатыми средствами редактирования, в ClassExplorer реализованы специализированные алгоритмы, которые более востребованы при документировании примеров программирования.
Властью, данной мне в моём блоге, объявляю перемирие: оба инструмента остаются на моей полке в качестве партнеров в общем деле разработки программного обеспечения и образования.
Да, Да, я тоже решил заменить среду разработки для программы question..