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

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

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

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



29.11.2012

Обзор

В процесс реализации ИТ-решения входит интеграция и настройка различных программных и аппаратных компонентов. Соответствующая документация и другая техническая информация, составляющая «руководство по уходу и кормлению» для реализованного решения, может состоять из работ многих авторов, расположенных в разных местах материалов и документов самых разнообразных форматов — от традиционных лабораторных и офисных документов до форумов, блогов и вики. Процесс сбора, организации и доставки документации клиентам (или боссу/коллегам) может оказаться трудоемким, особенно если вы не специализируетесь в области документации. Альтернативой является предоставление неадекватной документации, что чревато дополнительными расходами, попосту потраченным временем и подрывом доверия клиентов.

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

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

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

Рисунок 1. База знаний по Project Zero WebSphere sMash
База знаний по Project Zero WebSphere sMash

Если вы предоставите клиенту информационный центр решения вместе с проектом, который использовался для его создания, то он сможет дополнять этот информационный центр новой документацией на протяжении всего жизненного цикла решения. Инструментарий для разработки и обновления специализированных информационных центров доступен бесплатно на портале IBM® alphaWorks.

Предлагаемый на портале alphaWorks инструментарий Toolkit for Custom and Reusable Solution Information помогает построить информационный центр для передачи клиенту или для коллективной работы с коллегами. Вначале информационный проект решения представляет собой графическое дерево навигации, куда можно перетаскивать информацию, например, файлы презентаций. Вскоре ― без всяких информационных разработок и не имея никакого опыта пользования ― вы получаете заготовку проблемно-ориентированного информационного центра решения. Этот автономный информационный центр можно экспортировать клиентам для работы на ПК, в корпоративной сети или в Интернете.

Инструментарий позволяет:

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

Платформа Eclipse располагает своей собственной справочной системой, основанной на XML-оглавлении, которое ссылается на HTML-файлы, как описано в статье Документирование вашего проекта с использованием справочной системы Eclipse. Справочную систему не нужно интегрировать в интерфейс пользователя программного продукта. Она может работать автономно. Ее достаточно создать один раз, а затем легко переносить с рабочего стола в интрасеть или в Интернет. Эти свойства делают справочную систему Eclipse удобным средством предоставления полностью автономной, самодостаточной документации (т.н. информационный центр).

Инструментарий Toolkit for Custom and Reusable Solution Information делает мощную систему доставки информации на основе Eclipse доступной для всех, даже если это не программисты или разработчик информационных Web-сайтов. Он обеспечивает графический интерфейс drag-and-drop, который позволяет создавать информационные центры на основе Eclipse, содержащие нужную вам информацию, не обладая никакими знаниями в области написания плагинов для Eclipse.


Создание специального информационного центра решения

Итак, вы готовы создать свой первый информационный центр? Для начала нужно получить инструментарий Toolkit for Custom and Reusable Solution Information на портале developerWorks и установить его. Инструментарий упакован в ZIP-файл. Установка сводится к извлечению содержимого этого ZIP-файла. Затем откройте инструментарий и войдите в рабочую область, откуда можно начать проект информационного центра решения.

Для этого:

  1. Дважды щелкните на файле run.bat, чтобы запустить графический интерфейс пользователя инструментария.
    Рисунок 2. Дважды щелкните на run.bat, чтобы запустить инструментарий
    Дважды щелкните на run.bat, чтобы запустить инструментарий
  2. Когда появится экран приветствия, нажмите кнопку Workbench, как показано на рисунке 3. Обратите внимание на другие кнопки для чтения обзора, поиска руководств и т.п.
    Рисунок 3. Экран приветствия с нажатой кнопкой Workbench
    Экран приветствия с нажатой кнопкой Workbench
  3. Начните проект информационного центра, соответствующего определенному решению.
    1. Выберите из меню File > New > Solution information project. Появится диалоговое окно нового проекта информационного центра решения.
    2. Укажите имя проекта, например Cloud computing solution for J.K. Enterprises.
    3. Нажмите кнопку Finish.

Появится шаблон навигатора, который можно настраивать и наполнять содержанием.


Настройка навигатора информационного центра

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

Чтобы настроить форму шаблона навигатора для конкретного проекта:

  1. Выберите раздел навигационного шаблона (желтый прямоугольник), например, My solution. Он станет ярко-желтым.
  2. Дважды щелкните на записи, чтобы войти в режим редактирования надписи.
  3. Измените надпись, например, на Cloud computing solution for J.K. Enterprises. (В процессе редактирования навигатора в начале записи отображается цифра 0, но в готовом информационном центре решения она отображаться не будет).
  4. Чтобы сохранить изменения в текущей записи навигатора, выберите другую запись.
Рисунок 4. Настройка навигатора
Частично настроенный навигатор

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


Сбор нужной информации

Подумайте, какую новую и уже имеющуюся информацию было бы полезно собрать и объединить в навигаторе. Определите файлы, такие как образцы кода, мультимедиа и офисные документы. Подумайте о внутренних или внешних Web-сайтах, вики или базах данных IBM Lotus Notes® с полезной информацией.

Типы информации, поддерживаемые инструментарием

  • Файлы: локальные документы, такие как презентации, электронные таблицы, демонстрации и образцы кода.
  • Web-контент: Web-страницы, которые можно указать или загрузить в инструментарий для создания локальных копий.
  • Каналы: каналы RSS и ATOM, помогающие пользователям находить последние по времени материалы.
  • Заметки: документы, экспортированные из пространства групповой работы Lotus Notes, или ссылки на документы в Web-интерфейсах Notes.
  • Книги: плагины документации Eclipse, которые представляют собой универсальные единицы компоновки, понятные информационным центрам.

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

  • поиск информации на Web-сайте IBM.com и ее ввод;
  • импортирование и экспортирование содержимого библиотеки для совместной работы с другими пользователями инструментария;
  • импортирование плагинов справочной системы Eclipse, стандартной упаковки документации продуктов IBM;
  • импортирование представлений Lotus Notes, экспортированных из Notes в формате XL;
  • использование диалоговых окон настройки для добавления отдельных документов.

Начните с диалогового окна настройки, добавив файл из локальной файловой системы.

  1. Просмотрите этот файл (годится любой файл):
    1. Выберите из меню Window > Show View > Files. На передний план выйдет страница вкладки Files, как показано на рисунке 5. Обратите внимание на другие страницы, где можно добавлять другие материалы.
      Рисунок 5. Добавление файлов
      Добавление файлов
    2. Нажмите кнопку Add Files (Добавить файлы).
    3. В мастере создания файлов придерживайтесь группы default. Группы работают как набор выдвижных ящиков, в которых хранятся ваши материалы.
    4. Укажите имя, которое будет отображаться при навигации, например, «Обзор облачных вычислений», если это соответствует описанию ваших файлов.
    5. Нажмите кнопку Обзор, а затем воспользуйтесь окном проводника для поиска документа в файловой системе.
    6. Вернувшись в Files Wizard, нажмите кнопку Next (Далее).
  2. Укажите сведения для страницы, которая будет представлять этот файл пользователям:
    1. Укажите заголовок HTML-страницы, которую инструментарий сгенерирует, чтобы рассказать читателям информационного центра о вашем файле.
    2. Составьте описание, чтобы помочь пользователям решить, следует ли просматривать файл.
    3. При необходимости укажите издателя, которым можете быть вы сами, ваша компания, автор файла или кто-то еще.
    4. Укажите ключевые слова для поиска в информационном центре.
    5. Нажмите кнопку Finish. Вы увидите свой файл в списке группы default на странице вкладки Files.

Настройка многократно используемых файлов

После ввода файла в инструментарий его можно отредактировать прямо там. Найдите файл на странице вкладки Files. Щелкните на файле правой кнопкой мыши и выберите Edit with... для отображения списка редакторов. Редактор по умолчанию ― это, как правило, редактор, определенный в операционной системе Windows®. Сохраняя файл, вы сохраняете версию, настроенную на многократное использование в любом из проектов информационных центров ваших решений.


Заполнение навигатора

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

Чтобы добавить файл в навигатор:

  1. Откройте страницу вкладки Files.
  2. Войдите в группу default.
  3. Найдите в группе default свой файл.
  4. Щелкните на файле. Перетащите его в навигатор, где он представлен новым разделом.

Например, на рисунке 6 показано, как выглядит файл Product presentation, указанный на странице вкладки Files и отбуксированный в навигатор. На рисунке 6 показано также, как использовать группу sample project с несколькими файлами. (Кстати, недалеко от кнопки Add Files, которой вы уже пользовались, находится кнопка Add Group [добавить группу]).

Рисунок 6. Добавление материалов в навигатор
Добавление материалов в навигатор

Настройка заголовка в браузере и главной страницы информационного центра

Информационный центр отображается в Web-браузере, независимо от того, выполняется ли он на рабочем столе, в интрасети или в Интернете. Имя информационного центра отображается в заголовке окна Web-браузера.

Чтобы указать имя информационного центра в строке заголовка браузера:

  1. Выберите в меню инструментария Information Center > Browser Title.
  2. Укажите заголовок, например, Cloud computing solution for J.K. Enterprises.
  3. Нажмите на значок «X» на вкладке Browser Title, чтобы сохранить изменения и выйти.

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

Чтобы настроить главную страницу информационного центра:

  1. Выберите из меню Information Center > Home Page.
  2. Укажите заголовок страницы, например, Cloud computing solution for J.K. Enterprises.
  3. Укажите различные элементы информации ― все они необязательны.
  4. Нажмите на значок «X» на вкладке Home Page, чтобы сохранить изменения и выйти.
Рисунок 7. Ввод информации для главной страницы
Ввод информации для главной страницы

На рисунке 8 показана сгенерированная главная страница с информацией, представленной на рисунке 7.

Рисунок 8. Главная страница
Главная страница

Кстати, после экспорта информационного центра из инструментария главная страница включается как файл index.html наряду с CSS-файлом (welcome.css), что позволяет подправить ее внешний вид. Можно настроить стили шрифтов, их размеры, цвет фона и т.д.

Альтернативный подход к созданию главной страницы ― импортирование домашней страницы HTML из локальной системы. Страница должна называться index.html. Выберите из меню Information Center > Home page , но вместо заполнения шаблона главной страницы нажмите кнопку Directory со страницей index.html и следуйте инструкциям.


Предварительный просмотр информационного центра

Невидимый план навигации

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

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

Для предварительного просмотра информационного центра:

  1. Выберите из меню Information Center > Preview.
  2. Дождитесь отображения информационного центра. Смотрите на статус в области Console внизу окна инструментария.
  3. Когда информационный центр появится, попробуйте возможности дерева навигации и поиска.
  4. Когда закончите просмотр, нажмите на значок «X» на вкладке Preview.
Рисунок 9. Предварительный просмотр информационного центра
Предварительный просмотр информационного центра

Обратите внимание, что инструментарий генерирует разные HTML-страницы для отображения предоставленной информации о файлах и других материалов из библиотеки. В числе этих страниц есть графический заполнитель (site.gif), который можно заменить любым рисунком. Например, стрелку рядом с заголовком Product presentation на рисунке 9 можно заменить логотипом компании или проекта. Замените графику, когда будете экспортировать информационный центр для клиента.

Совет по устранению неполадок: если в какой-то момент инструментарий зависнет или перестанет реагировать, не бойтесь закрыть его, пользуясь значком «X» в правом верхнем углу. Нажмите кнопку ОК в ответ на любые сообщения инструментария. После перезапуска он вернется к нормальному поведению. Зависание чаще всего происходит при просмотре информационных центров.


Выпуск информационного центра

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

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

  1. Выберите из меню Information Center > Export.
  2. В появившемся диалоговом окне Package solution information укажите место назначения экспортируемого информационного центра. Нажмите кнопку Finish.
  3. Пока информационный центр экспортируется в ZIP-файл, можно продолжать работать с инструментарием, решая другие задачи.

Проверка готового информационного центра

Проверьте шаги, которые должен будет проделать получатель информационного центра вашего решения.

  1. Извлеките информационный центр решения из файла *_package.zip.
  2. Перейдите в каталог, содержащий пакетный файл запуска информационного центра IC_start.bat.
  3. Откройте файл IC_start.bat в текстовом редакторе, например Notepad.
  4. Можно установить аргумент -port, например -port 8888. При необходимости измените порт.
  5. Закройте файл IC_start.bat. Дважды щелкните на файле IC_start.bat, чтобы запустить его. Отображается системное окно command, показывая процесс.
  6. Воспользуйтесь Web-браузером для просмотра информационного центра.
    • (Необязательно) Проверьте информационный центр на своем собственном рабочем столе, указав адрес: http://localhost:8888/help/index.jsp
    • Попробуйте удаленный просмотр информационного центра, указав адрес: http://your.host.name:8888/help/index.jsp

Чтобы выключить информационный центр, дважды щелкните на IC_end.bat и закройте окно браузера.

На рисунке 10 приведен пример информационного центра решения, в котором выполняется демонстрация.

Рисунок 10. Пример информационного центра, созданного с помощью инструментария
Пример информационного центра, созданного с помощью инструментария

Заключение

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

Ресурсы

Научиться

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

Обсудить

  • Группы новостей о платформе Eclipse ― первая остановка на пути решения вопросов, касающихся Eclipse. (Выбор этого пункта приведет к запуску приложения для чтения новостей Usenet по умолчанию и открытию eclipse.platform.)
  • Группы новостей по Eclipse содержат много ресурсов для тех, кто интересуется применением и расширением платформы Eclipse.

Комментарии

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=847765
ArticleTitle=Документирование ИТ-решений с помощью специальных информационных центров Eclipse: Часть 1. Как создать свой первый информационный центр
publish-date=11292012