Документирование ИТ-решений с помощью специальных информационных центров Eclipse: Часть 2. Ускоренный ввод и многократное использование информации

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

Триша Йорк Гарретт, архитектор информации, IBM

Триша Йорк ГарреттТриша Йорк Гарретт (Tricia York Garrett) работает архитектором информации в группе документации IBM WebSphere Application Server. Она ― один из руководителей внутренней рабочей группы по изучению простых, масштабируемых и автоматизированных подходов, позволяющих отдельным людям и группам легко и качественно документировать свои ИТ-проекты. Собрала требования специалистов по ИТ-решениям, что позволило начать разработку набора инструментов Toolkit for Custom and Reusable Solution Information.



29.11.2012

Обзор

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


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

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

Чтобы импортировать проект информационного центра:

  1. Загрузите файл TKCARSI-SAMPLE.zip из раздела Загрузки этой статьи.
  2. В инструментарии выберите из меню File > Import project. Появится диалоговое окно Import Solution (Импортировать решение).
  3. Перейдите в то место, куда вы загрузили пример информационного проекта TKCARSI-SAMPLE.zip.
  4. Вернувшись в диалоговое окно Import Solution, нажмите кнопку Finish. Инструментарий сообщит, что он сканирует проект.
  5. Когда инструментарий отобразит диалоговое окно со списком материалов, которые будут добавлены или перезаписаны, проверьте этот список, а затем нажмите кнопку ОК.
  6. Следите за индикатором хода выполнения операции. Как правило, любые сообщения об ошибках можно игнорировать.

Когда проект импортирован, инструментарий открывает свое дерево навигации, как показано на рисунке 1. Если вы не хотите работать с проектом прямо сейчас, то его можно просто закрыть (File > Close project). Содержание проекта добавлено в библиотеку и готово к применению в любом информационном центре. Импортированный проект теперь доступен по команде File > Open project.

Рисунок 1. Пример проекта информационного центра
Пример проекта информационного центра

Поиск и ввод материалов с сайта IBM.com

Второй способ быстрого накопления контента ― использование встроенного в инструментарий механизма IBM® Support Assistant для поиска и ввода материалов с Web-сайта IBM. Вводить можно копии Web-страниц или ссылки на страницы.

Чтобы заполнить библиотеку материалами с сайта IBM.com:

  1. Получите набор результатов поиска.
    1. В строке меню инструментария выберите Search > Search the Internet.
    2. Когда появится диалоговое окно Search Wizard, выберите целевые объекты поиска. Это разделы Web-сайта IBM, в которых инструментарий будет искать материалы. По умолчанию выбраны все возможные целевые объекты. Чем их меньше, тем быстрее поиск. Для практики отмените выбор всех целевых объектов поиска, за исключением IBM developerWorks.
      Рисунок 2. Целевые объекты поиска
      Целевые объекты поиска
    3. В поле поиска введите условия, по которым нужно искать. Обратите внимание на параметр Advanced Search (Расширенный поиск), который позволяет адаптировать поиск для каждого целевого объекта, например, ограничить поиск определенным видом продуктов IBM. Чтобы попрактиковаться, введите в качестве условия поиска cloud computing (без кавычек).
      Рисунок 3. Диалоговое окно поиска
      Диалоговое окно поиска
    4. Нажмите кнопку Go!. Обратите внимание, как инструментарий сообщает результаты поиска.
  2. Выберите те результаты, которые желательно сохранить в инструментарии. На следующем шаге вы формализуете свой выбор.
    1. В области результатов поиска щелкните на названии продукта, например, Information Management.
      Рисунок 4. Результаты поиска
      Результаты поиска
    2. Просмотрите результаты и выберите статьи, которые вы хотели бы добавить в свой информационный центр. Чтобы попрактиковаться, щелкните на Select All (Выбрать все), чтобы ввести первые 10 результатов.
      Рисунок 5. Отбор результатов поиска
      Отбор результатов поиска
    3. Закончив просмотр и выбрав результаты, нажмите кнопку Next (Следующий). Выбранные результаты отображаются в области сохранения результатов поиска на странице библиотеки диалогового окна Search Wizard.
  3. Сузьте выбор до тех результатов поиска, которые вы определенно хотели бы сохранить.
    1. В области Search Results Selected (Выбранные результаты поиска) выберите несколько результатов поиска, которые нужно сохранить. Чтобы выбрать несколько результатов за раз, удерживайте кнопку Control, щелкая на каждом результате.
      Рисунок 6. Область выбранных результатов поиска
      Область выбранных результатов поиска
    2. При необходимости в области Search Results to Save можно выбрать группу материалов, в которой вы хотели бы сохранить выбранные результаты. Группы напоминают выдвижные ящики стола, куда кладут материалы.
    3. Нажмите кнопку Add>, чтобы сохранить выбранные результаты в выбранной группе.
      Рисунок 7. Область Search Results to Save
      Область Search Results to Save
  4. Для сохраняемых результатов решите, следует ли сохранять копии Web-страниц, или только ссылки на них.

    Используйте кнопки под областью Search Results Selected.

    • Чтобы сохранить ссылки на страницы, нажмите кнопку Create a link to the Web page.
    • Чтобы сохранить копии, выберите Download the Web page content и укажите глубину вложения страниц. Пример:
      • при глубине 1 сохраняется сама страница со всей графикой и стилевым оформлением;
      • при глубине 2 сохраняется страница и один уровень страниц, на которые она ссылается;
      • При глубине 3 сохраняется страница, уровень страниц, на которые она ссылается, и страницы, на которые ссылаются эти страницы.
  5. Завершение ввода результатов поиска.
    1. Нажмите кнопку Finish. Диалоговое окно извлечения Web-страниц информирует о ходе процесса.
    2. Когда ввод окончен, проверьте вкладку Web Pages библиотеки на наличие новых страниц. Их можно перетащить в дерево навигации проекта информационного центра.
      Рисунок 8. Результат поиска в библиотеке
      Результат поиска в библиотеке
      В зависимости от цели поиска инструментарий иногда может вводить некоторые детали в дополнение к заголовку Web-страницы и ссылке. Например, нажав кнопку редактирования свойств Web-страницы, вы заметите, что описание введено из статьи в IBM developerWorks, а ключевые слова отражают условия поиска.
      Рисунок 9. Заполненные детали результатов поиска
      Заполненные детали результатов поиска

Добавление подключаемых модулей документации продуктов IBM

Третий быстрый способ ввода материалов ― импортирование подключаемых модулей документации Eclipse. Подключаемые модули документации Eclipse — это стандартный формат упаковки для отображения материалов в справочной системе Eclipse, такой как информационный центр. При получении подключаемого модуля он находится в файле архива, например, в формате ZIP или TAR. Подключаемые модули доступны из многих страниц библиотеки продуктов IBM, а иногда они устанавливаются вместе со справочной системой продукта. Чтобы найти подключаемые модули документации, ищите файлы или каталоги с шаблоном имени com.ibm.*.doc*, где * ― подстановочный знак.

Следующая процедура основана на подключаемом модуле IBM WebSphere Help System: Virtual Enterprise (бывший Operations Optimization), который можно загрузить из библиотеки WebSphere Extended Deployment.

Чтобы добавить плагин в свою библиотеку:

  1. Загрузите подключаемый модуль документации с Web-сайта и извлеките его содержимое в свою файловую систему.
  2. Просмотрите загруженный модуль документации или тот, что был установлен вместе с продуктом.
    1. Выберите из меню Window > Show View > Books. На передний план выйдет вкладка Books.
    2. Нажмите кнопку Add Books (Добавить книги), чтобы вызвать мастер New Books.
    3. В мастере New Books нажмите кнопку Directory: Browse, что приведет вас в корневой каталог модуля.
    4. Нажмите кнопку Browse, затем перейдите к искомому модулю в своей файловой системе. Это не совсем прямолинейный процесс. Если имеются вложенные каталоги com.ibm, выберите самый внутренний каталог, как показано на рисунке 10.
      Рисунок 10. Выбор каталога подключаемого модуля
      Выбор каталога подключаемого модуля
    5. Вернувшись в мастер New Books, проверьте параметры настройки, как показано на рисунке 11, а затем нажмите кнопку OK.
      Рисунок 11. Параметры настройки мастера New Books
      Параметры настройки мастера New Books
    6. В ответ на вопрос "Do you want to copy the content from the original directory into the toolkit?" (Скопировать содержимое из исходного каталога в инструментарий?) нажмите кнопку Yes.
    7. Если появится диалоговое окно, уведомляющее, что некоторые из искомых файлов потеряют свою роль основных навигационных файлов, нажмите кнопку ОК. Это просто означает, что любые навигационные представления в модуле документации будут подчинены основному навигационному представлению информационного проекта.
  3. Перетащите разделы навигации из модуля в свой собственный шаблон навигатора.
    1. Просмотрите вкладку Books инструментария.
    2. Щелкните на соответствующей группе материалов, чтобы увидеть файлы навигации, доступные внутри модуля. В данном случае группа называется WebSphere® Virtual Enterprise Edition Version 6.1, а файлы навигации имеют такие имена, как prodovr.xml.
      Рисунок 12. Содержимое модуля добавлено в библиотеку
      Содержимое модуля добавлено в библиотеку
    3. Разместите в навигаторе некоторые или все файлы навигации.
      Рисунок 13. Содержимое модуля включено в навигатор
      Содержимое модуля включено в навигатор
  4. Просмотрите информационный центр, чтобы проверить и при необходимости исправить результаты.
    Рисунок 14. Содержимое модуля отображается в информационном центре
    Содержимое модуля отображается в информационном центре

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


Автоматическое объединение содержимого модулей

Лучший способ: Automatic Merge Links

  • Добавление новых разделов навигации не мешает впоследствии объединять содержимое.
  • Реорганизация разделов не мешает процессу слияния находить разделы в новых местах.
  • Удаление разделов лишает их возможности получать объединенные материалы.
  • Переименование раздела при сохранении его первоначального назначения, например «Устранение неполадок» вместо «Решение проблем», допускается.
  • Переназначение раздела, например, переименование раздела «Разработка бизнес-приложений» в «Реализация управления SOA», может привести к странным результатам при позднейшем объединении содержимого в навигаторе. Лучше по мере необходимости создавать новые разделы навигации.

Добавив в инструментарий модуль документации, перетащите его содержимое в навигатор своего проекта информационного центра. А можно ли одной кнопкой заставить инструментарий распределить содержимое модулей по соответствующим местам? Можно, если в модуле включена функция Automatic Merge Links. К этой статье прилагается файл TKCARSI-TEMPLATE.zip, который можно использовать для работы с функцией Automatic Merge Links, а также в качестве спецификации и для пробной реализации подключаемых модулей.

Чтобы попробовать функцию Automatic Merge Links:

  1. Получите модуль com.ibm.soln.TEMPLATE.enabled.doc_1.0.0.
    1. Загрузите файл TKCARSI-TEMPLATE.zip из раздела Загрузки.
    2. Извлеките содержимое, чтобы получить каталог com.ibm.soln.TEMPLATE.enabled.doc_1.0.0.
  2. Добавьте модуль документации в свой инструментарий.
    1. Выберите из меню Window > Show View > Books. На передний план выйдет вкладка Books.
    2. Нажмите кнопку Add Books (Добавить книги), чтобы вызвать мастер New Books.
    3. В мастере New Books нажмите кнопку Directory: Browse, которая ведет в корневой каталог модуля.
    4. Нажмите Browse, затем перейдите в папку com.ibm.soln.TEMPLATE.enabled.doc_1.0.0 своей файловой системы.
    5. Вернувшись в мастер New Books, нажмите кнопку ОК.
    6. В ответ на вопрос "Do you want to copy the content from the original directory into the toolkit?" (Скопировать содержимое из исходного каталога в инструментарий?) нажмите кнопку Yes.
  3. Создайте новый проект информационного центра или откройте существующий. Для данной демонстрации рекомендуется создать новый проект, особенно если вы удаляли или изменяли разделы в навигаторе по умолчанию. Если вы просматриваете информационный центр, выйдите из режима предварительного просмотра перед выполнением операции Automatic Merge Links.
  4. Нажмите кнопку Automatic Merge Links. На рисунке 15 показано ее местоположение. Кнопка становится активной, когда дерево навигации информационного центра открыто, и в выбранной книге (модуле документации) включена функция Automatic Merge Links. В противном случае кнопка Automatic Merge Links остается серой.
    Рисунок 15. Расположение кнопки Automatic Merge Links
    Расположение кнопки Automatic Merge Links
  5. Подтвердите операцию слияния и наблюдайте за ней. При запросе подтверждения нажмите кнопку Yes. Инструментарий сообщит, сколько разделов навигатора заполнено содержимым из модуля. В случае модуля TKCARSI-TEMPLATE около 100 разделов навигатора получают из модуля один или несколько документов. Чтобы увидеть результаты, разверните дерево навигации своего проекта информационного центра.
    Рисунок 16. Содержимое шаблона, перенесенное в дерево навигации
    Содержимое шаблона, перенесенное в дерево навигации
  6. Рассмотрите информационный центр, чтобы изучить результаты, как показано на рисунке 17. В частности, обратите внимание, что один из разделов навигатора может получить из модуля несколько документов. Например, в раздел Demonstrate the template > Solution overview > Business context > Overview добавлены три элемента навигации.
    Рисунок 17. Содержимое шаблона, отображаемое в режиме предварительного просмотра
    Содержимое шаблона, отображаемое в режиме предварительного просмотра

Чтобы включить функцию Automatic Merge Links для модуля документации, автор модуля вводит в него специальную строку комментариев. Файл TKCARSI-TEMPLATE.zip содержит спецификацию и эталонную реализацию для авторов модулей.

Внутри подключаемого модуля TKCARSI-TEMPLATE.zip видны специальные строки комментариев.

  1. Если вы добавили модуль в свой инструментарий, перейдите в каталог: tkcarsi1.5\bigeasy\workspace\content\com.ibm.soln.TEMPLATE.enabled.doc_1.0.0. В противном случае перейдите в то место своей файловой системы, куда была загружена информация из подключаемого модуля. Каталог содержит XML-файлы, которые определяют записи навигации для документов из модуля. Модуль TKCARSI-TEMPLATE.zip содержит XML-файл, соответствующий каждому месту в навигаторе по умолчанию, отображаемому инструментарием при запуске нового проекта информационного центра.
  2. Просмотрите файл Soln_Business_context_OVERVIEW.xml в текстовом редакторе. Обратите внимание на вторую строку, которая начинается с выражения <--Target=. В каждом XML-файле вы найдете аналогичный зависящий от регистра целевой оператор, указывающий, куда отнести материал в навигаторе информационного центра. Если комментарий присутствует, имя XML-файла не имеет значения.
Листинг 1. Файл Soln_Business_context_OVERVIEW.xml
<?xml version="1.0" encoding="utf-8"?>
<!-- Target=Soln_Business_context_OVERVIEW -->
<!--Arbortext, Inc., 1988-2005, v.4002-->
<?APT Element gi="toc" attrs="label topic link_to"?>
<?APT Element gi="topic" attrs="label href"?>
<?APT Element gi="anchor" empty="yes" attrs="id"?>
<?NLS TYPE="org.eclipse.help.toc"?><!--Nav fragment example-->

<toc label="This will not show" topic="This will not show">
<topic label="BUSINESS CONTEXT OVERVIEW" href="topics/Business context overview.html">
</topic>
<topic label="VALUE PROPOSITION" href="topics/Value-proposition.html">
</topic>
<topic label="WHO BENEFITS FROM THIS SOLUTION" href="topics/Who-benefits.html">
</topic>
</toc>

Импортирование представлений из баз данных IBM Lotus Notes

Четвертый и последний из быстрых способов накопления материалов ― это импортирование набора документов IBM Lotus Notes® в формате XML Domino® (DXL). Вы можете экспортировать весь набор документов из представления базе данных Lotus Notes, например, определенную папку базы данных электронной почты. Или импортировать весь набор для повторного использования в своем информационном центре. Обратите внимание на ограничение: инструментарий импортирует содержимое документов Lotus Notes, но не их вложения.

Чтобы импортировать набор документов Lotus Notes в инструментарий:

  1. Найдите локальный DXL-файл, содержащий экспортированные документы Lotus Notes.
    1. Выберите из меню Window > Show View > Notes. На передний план выйдет вкладка Notes.
    2. Нажмите на значок Add Lotus Notes content.
    3. В мастере Notes Content выберите группу для управления контентом, например, default.
    4. Выберите FromDXL.
    5. Укажите имя, которое будет отображаться в навигаторе, например, Identity management project plan (План проекта управления учетными записями).
    6. Нажмите кнопку Browse, затем перейдите по онлайн-адресу документа Notes.
    7. Нажмите кнопку ОК, чтобы закрыть диалоговое окно просмотра файлов.
    8. Вернувшись в мастер Notes Content, нажмите кнопку Next.
  2. Найдите набор документов Notes в инструментарии и перетащите его в навигатор.
    1. Вернитесь на вкладку Notes.
    2. Дважды щелкните на серой панели группы, к которой должны принадлежать документы.
    3. Найдите набор документов Notes по имени, присвоенному набору документов.
    4. Выберите документы.
    5. Перетащите документы в навигатор.

Описание способа написания программы LotusScript, которая экспортирует документы Notes в формате DXL, выходит за рамки этой статьи, но в Интернете есть справочная информации по программированию Lotus Notes и формату DXL. Для тех, кто уже знаком с программированием для Lotus Notes, вот обзор испытанного подхода к экспорту набора документов:

  1. Создайте локальную копию своей базы данных Notes, если это единственное место, где вам разрешено создавать новые представления.
  2. Выберите Create > View из меню в Lotus Notes. В инструкции SELECT укажите, какие документы отображается в представлении.
  3. Выберите Save and Customize (сохранять и настраивать); откроется панель программиста Lotus Notes.
  4. На панели программиста выберите Create > Action и настройте новое действие ExportDXL.
  5. Измените действие ExportDXL, добавив сценарий LotusScript, экспортирующий документы в представление в виде файла .dxl в указанное место системы.
  6. Сохраните действие и закройте панель программиста.
  7. Посмотрите на свое новое представление с кнопкой ExportDXL вверху.
  8. Проверьте LotusScript, нажав кнопку ExportDXL и просмотрев каталог, где должен оказаться файл .dxl.

Заключение

Вы познакомились с четырьмя методами накопления материалов для документирования своего ИТ-решения в виде информационного центра, созданного с помощью инструментария Custom and Reusable Solution Information Toolkit. Конечно, стоит только ввести материалы, как появляется риск их устаревания. В следующей статье цикла Документирование ИТ-решений с помощью специальных информационных центров Eclipse я покажу, как управлять изменениями в многократно используемых материалах.


Загрузка

ОписаниеИмяРазмер
Шаблон подключаемого модуля документированияos-eclipse-infocenter2-TKCARSI-TEMPLATE.zip266 КБ
Пример проекта информационного центраos-eclipse-infocenter2-TKCARSI-SAMPLE.zip11000 KB

Ресурсы

Научиться

Получить продукты и технологии

Комментарии

developerWorks: Войти

Обязательные поля отмечены звездочкой (*).


Нужен IBM ID?
Забыли Ваш IBM ID?


Забыли Ваш пароль?
Изменить пароль

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


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

Вся введенная информация защищена.

Выберите имя, которое будет отображаться на экране



При первом входе в developerWorks для Вас будет создан профиль и Вам нужно будет выбрать Отображаемое имя. Оно будет выводиться рядом с контентом, опубликованным Вами в developerWorks.

Отображаемое имя должно иметь длину от 3 символов до 31 символа. Ваше Имя в системе должно быть уникальным. В качестве имени по соображениям приватности нельзя использовать контактный e-mail.

Обязательные поля отмечены звездочкой (*).

(Отображаемое имя должно иметь длину от 3 символов до 31 символа.)

Нажимая Отправить, Вы принимаете Условия использования developerWorks.

 


Вся введенная информация защищена.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=40
Zone=Open source
ArticleID=847792
ArticleTitle=Документирование ИТ-решений с помощью специальных информационных центров Eclipse: Часть 2. Ускоренный ввод и многократное использование информации
publish-date=11292012